The Gallery Block
The complete inspector reference. Every panel, every control, what it defaults to, and when it appears.
The Shaped Gallery block is the whole product. There's one block, its layout is a setting, and everything else — media, styling, behaviour — is configured from the inspector, the settings sidebar on the right of the editor.
This page documents every panel the block has. The layout pages cover only what's unique to each layout and link back here for the rest, so read this one once and you'll know your way around all seven.
Adding the block
- Open a page or post in the block editor.
- Click + (Add Block) and search for Shaped Gallery.
- Insert it. Because the gallery is empty, the block opens on the layout picker.
- Pick a layout — a card grid showing all seven.
- Click Add from Media and choose images or videos. Add to Gallery closes the picker.
Expected result
As soon as media is added, a live preview appears on the canvas and the inspector opens on the right. Every change updates the preview immediately — you don't need to save to see it.
The block toolbar
Two buttons sit on the block's own toolbar, above the gallery on the canvas:
| Button | What it does |
|---|---|
| Change Layout | Opens a compact grid of layout swatches — a quick-switch for an existing gallery. Your images, categories, captions and every shared setting carry over. |
| Edit Gallery | Opens the Edit Gallery modal: reorder, remove, assign categories, and edit each item's alt text, title, caption, description and custom URL. |
Clicking a tile selects the image, not the gallery
Tiles on the canvas are real, draggable image blocks — grab one and drag it to reorder. The trade is that a click selects the image; to get back to the gallery's own panels, use the parent-block button or the breadcrumb at the bottom of the editor.
Finding your way around the inspector
The inspector is a stack of collapsible panels. Most have Settings and Style tabs.
| Panel | What it controls |
|---|---|
| Layout Settings | Which layout, its own controls, spacing, item order, and the pagination switch. |
| Image & Video Settings | Resolution, lazy loading, watermarking, video playback, hover animation, per-state image styling. |
| Content Settings | Titles and descriptions on each tile, Classic or Overlay, and their typography. |
| Image Click Action | What happens when a visitor clicks a tile. |
| Ajax Pagination | Load More, infinite load or numbered pages (shown when the switch is on). |
| Image Filter & Search | The category filter bar and the search field. |
| Motion Effects | Entrance animations as the gallery scrolls into view. |
| Advanced Settings | Wrapper background and spacing, visibility and password, CSS hooks. |
Above all of them, under the block card, sits Gallery Info — a documentation link, and (on a saved gallery) that gallery's permanent shortcode.
Two layouts show fewer panels
Thumbnails and Perspective Scrolling own their own item model, so the panels that wouldn't mean anything there are hidden rather than shown-but-inert. See which panels each layout shows.
Responsive controls
Many controls carry a small device switcher — desktop, tablet, phone — next to their label. It changes which device you're editing, not which device you're previewing:
- Click the device icon and pick Tablet.
- Set the value you want on tablet.
- Switch back to Desktop. Your desktop value is untouched.
Columns, gaps, most sizes and the description limit all work this way. Where a control isn't responsive, this page says so.
To preview a breakpoint, use WordPress's own Desktop / Tablet / Mobile switcher in the editor's top bar.
Layout Settings
The first panel, and the only one whose contents change with the layout. It opens expanded.
At the top is the layout source row: a thumbnail of the current layout and its name. Below that come the controls that layout offers, then the controls every layout shares.
The layout's own controls
Each layout adds its own settings here. In brief:
| Layout | Its own controls |
|---|---|
| Automatic Justified | Maximum Row Height (Auto / Custom + a row-height slider). |
| Grid · Masonry | Columns. |
| Metro | None — the mosaic is a fixed pattern. |
| Staggered | Columns, Image Height (Original / Custom), Preserve Layout Gaps. |
| Thumbnails | A whole Settings / Style tab pair — strip position, size, active style, slider behaviour. |
| Perspective Scrolling | Gallery Size, Mode, Slide Direction and Speed, depth, rotation, edge fade, mouse tilt and parallax. |
Each layout page documents its own set in full.
Shared controls
These appear for Justified, Grid, Masonry, Metro and Staggered. Thumbnails and Perspective replace or interleave them with their own.
| Control | What it does | Default |
|---|---|---|
| Horizontal Gap | Space between tiles across a row. Responsive; units px, %, em; range 0–60. | 15 px |
| Vertical Gap | Space between rows. Responsive; units px, %, em; range 0–60. | 15 px |
| Order | Default keeps the order you arranged in the Edit Gallery modal. Random shuffles on each page load. | Default |
| Ajax Pagination | Switches on paging and reveals the Ajax Pagination panel. | Off |
Random order is a front-end behaviour
The editor always shows your stored order, even with Random on — a canvas that reshuffled itself while you were arranging it would be unusable. On the front end, one visit sees one shuffle, and paging through it keeps that same order rather than re-dealing on every page.
Image & Video Settings
Everything about the media itself: which file is served, how it loads, how video behaves, and how a tile looks at rest and on hover. Two tabs.
Settings tab
| Control | What it does | Default |
|---|---|---|
| Resolution | Which registered image size each tile serves: Thumbnail, Medium, Large, Full. Also acts as a ceiling on the responsive candidates the browser may pick, so it genuinely caps how much is downloaded. | Large |
| Lazy Load | Defer images below the fold until they're needed. Hidden entirely when the Lazy Load module is off. | On |
| Image Preloader | A shimmer placeholder in the tile while a deferred image arrives. Only shown while Lazy Load is on — with nothing deferred there's no gap to cover. | Off |
| Image Watermark | Serve watermarked copies of this gallery's images. The mark itself is configured site-wide — see Watermark. Hidden when the module is off. | Off |
| Right Click Protection | Block the context menu and image dragging on this gallery's tiles. Part of the Image Protection module. | Off |
| Video Play Mode | Inline plays the video in its tile; Popup opens it in the lightbox. | Inline |
| AutoPlay | Start inline video automatically. Browsers only allow this muted — see the note the panel shows. | On |
| Play Icon Size | The play badge on a video tile, 12–120 px. | 48 |
| Display Icon on Hover | Hide the play badge until the pointer is over the tile. | Off |
Resolution and Watermark don't show in the canvas
Both are resolved on the server, so the editor preview keeps showing your picked originals. Check the published page to see either one.
Style tab
The Style tab opens with two controls that apply to the whole gallery, then a Normal / Hover state switcher — everything below it is scoped to the state you've selected, so you set a resting look and a hover look from one set of controls.
| Control | What it does | Default |
|---|---|---|
| Hover Animations | Zoom, Lift, Tilt, Frame, Color Pop or None. See Hover Animations. | Zoom |
| Animation Duration | How long that animation takes, 0–2000 ms in steps of 50. | 500 ms |
| — Normal / Hover switcher — | Picks which state the controls below edit. | Normal |
| Image Filter | Brightness, contrast, saturation, hue, blur — the duotone-style adjustments, per state. | Unset |
| Image Opacity | 0–100 %, responsive. | 100 % |
| Image Overlay | A colour or gradient laid over the image, with its own Overlay Type and Overlay Opacity (0–1, step 0.1). | Off / 0.5 |
| Image Border | Border style, width and colour, per state. | None |
| Border Radius | Corner rounding, units px / % / em. | 0 |
| Box Shadow | Shadow, per state. | None |
| Margin | Space around each tile. Not per state — it applies to both. Units px / % / em. | 0 |
Hover styling is a second set of the same controls
Set the resting look with Normal selected, then flip to Hover and change only what should move. Anything you leave alone on Hover simply stays as it is.
Content Settings
Titles and descriptions drawn on each tile — where the text comes from, how it's laid out, and how it's styled. Two tabs.
Settings tab
| Control | What it does | Default |
|---|---|---|
| Image Title | Draw a title on the tile. Everything below it appears only when this is on. | Off |
| Image Title Source | Attachment Title or Attachment Caption. | Attachment Title |
| HTML Tag | H1–H6 or Span. Use a heading level that fits the page's outline. | H4 |
| Image Description | Draw a description under the title. | Off |
| Image Description Source | Attachment Caption or Attachment Description. | Attachment Caption |
| Description Limit | How much to show, counted in words or lines, responsive. Range 1–100. | 4 lines |
| Content Display Style | Classic puts the text under the image; Overlay puts it on top of the image. | Classic |
| Content Positions | (Classic) Text above or below the media: Top / Bottom. | Bottom |
| Content Alignment | Left / Center / Right. | Left |
| Title to Desc. Gap | Space between the two, responsive; units px / em / %. | 16 px |
Overlay sub-controls
Selecting Overlay reveals four more:
| Control | What it does | Default |
|---|---|---|
| Overlay Style | Full tints the whole tile with the text centred over it. Position anchors a box to one edge. | Full |
| Overlay Positions | (Position only) Center, Left, Right, Top, Bottom. | Center |
| Overlay Size | (Position only) How much of the tile the anchored box takes, 0–100 %. | 75 |
| Content Visibility | Always, or On Hover — the box slides in from the edge it's anchored to. | Always |
| Overlay Opacity | How dark the tint is, 0–1 in steps of 0.1. | 0.4 |
Overlay Opacity dims the photo, not the words
The tint is a separate layer behind the text, so turning it down makes the image easier to see without making the caption harder to read.
Thumbnails and Perspective only do Overlay
On those two layouts the Content Display Style control isn't shown, and content is drawn as an overlay. Your stored choice isn't rewritten — move the gallery back to another layout and Classic returns. Why →
Style tab
The typography controls for the title and description appear only when the matching toggle on the Settings tab is on — there's no point styling text the gallery doesn't render.
| Control | What it does |
|---|---|
| Title Typography | Family, weight, style, transform, decoration, size (responsive), line height, letter and word spacing. |
| Title Color | The title's colour. |
| Description Typography | The same set, for the description. |
| Description Color | The description's colour. |
| Content Background Style | Background colour or gradient behind the content region. Always available — it styles the region, not either piece of text. |
| Border · Border Radius · Padding | The content box. Radius and padding take px / % / em. |
More on titles and descriptions →
Image Click Action
What a visitor gets when they click a tile.
| Control | What it does | Default |
|---|---|---|
| Click Action Type | Lightbox opens the viewer. URL follows each item's own custom link. None makes the tile inert. | Lightbox |
| Lightbox Click Action | (Lightbox only) Full Image — the whole tile is the trigger. Icon — a small badge on the tile is the trigger, and the rest of the tile is not clickable. | Full Image |
Where the icon's own styling lives
Which icon, its style, position, visibility and offset are site-wide, under Settings → Modules → Lightbox, so you style your lightbox badge once instead of on every gallery. Lightbox →
The panel shrinks with your modules
Switching off the Lightbox module removes the Lightbox button; switching off Image Custom URL removes URL. If fewer than two choices remain, the panel disappears entirely — a one-button choice isn't a control. Your stored value is never rewritten: switch the module back on and it's exactly as you left it.
The Thumbnails layout never shows this panel at all, because its main slides deliberately ignore the click action.
Ajax Pagination
Appears once you switch Ajax Pagination on in Layout Settings. Large galleries ship a first page and fetch the rest on demand.
| Control | What it does | Default |
|---|---|---|
| Pagination Type | Load More (a button) or Number (numbered page links). | Load More |
| Infinity Load | (Load More) Fetch the next batch automatically as the visitor reaches the end, instead of waiting for a click. | Off |
| Show Per View | How many items the first view shows and how many each Load More or numbered page adds. Responsive, 1–100. | 15 |
| Button Label | (Load More) The button's text. | Load More |
| Ending Message | (Load More) Shown when there's nothing left. | No more images available |
| Select a Pagination Number Type | (Number) Number, Number + Arrow, or Number + Previous/Next with Arrow. | Number |
| Gap Between Numbers | (Number) Responsive; px / em / %. | 10 px |
| Alignment | Left / Center / Right. | Center |
The Style tab gives the button or number links typography, a Normal / Hover state switcher for text colour, background and border, plus border radius, inner padding and margin.
Full guide, including how pagination interacts with filtering →
Image Filter & Search
A category filter bar, an image search field, or both. Both are off by default.
| Control | What it does | Default |
|---|---|---|
| Image Filter | Show a category filter bar above the gallery. Needs categories. | Off |
| Filter Style | Minimal, Button or Dropdown. | Minimal |
| Display Count | Show how many images are in each category. | Off |
| Show 'All' | Include an "everything" chip. | On |
| Label for 'All' | Its text. | All |
| Gap Between Filters | Responsive; px / % / em; 0–60. | 16 px |
| Image Search | Show a search field. | Off |
| Search Bar Style | Minimal, Boxed, or With Button. | Minimal |
| Placeholder | Show placeholder text in the field. | On |
| Placeholder Text | Its text. | Search |
| Width | Field width, responsive; px or %. | 25 % |
| Alignment | (When only one of the two is on) Left / Center / Right. | Left |
| Filter & Search Orientation | (Both on) Inline or Stacked. | Inline |
| Filter & Search Gap | (Both on) Space between them, responsive. | 16 px |
| Justify Filter & Search | (Both on) Start, Center, End, Space Between, Space Around, Space Evenly. | Start |
"With Button" changes how search behaves
Minimal and Boxed search as you type. With Button searches only when the visitor presses the button or hits Enter — the right choice on a very large gallery.
The Style tab styles the filter chips (typography, Normal and Hover & Active states, corner radius), the filter area itself (background, full-width or hug, border, radius, inner padding, margin), and the search field (placeholder typography and colour, per-state icon and underline, inner padding).
Motion Effects
An entrance animation played as the gallery scrolls into view.
| Control | What it does | Default |
|---|---|---|
| Entrance Animation | Forty-plus animations, grouped as Fading, Zooming, Bouncing, Sliding, Rotating, Flipping, Rolling and Other. | None (Default) |
| Animation Speed | How long it runs, 0–5 s in steps of 0.1. (Shown once an animation is chosen.) | 1 s |
| Animation Delay | How long to wait first, 0–5 s in steps of 0.1. | 0 s |
Advanced Settings
Three sub-tabs: General, Visibility and Advanced.
General
| Control | What it does |
|---|---|
| Background | Colour or gradient behind the whole gallery. |
| Padding | Inside the gallery's wrapper. Responsive; px / % / em. |
| Margin | Outside it. Responsive; px / % / em. |
Visibility
| Control | What it does | Default |
|---|---|---|
| Visibility | Public — everyone sees it. Password — visitors must enter a password. Private — only logged-in users who can read private content see it; everyone else sees nothing at all. | Public |
| Set Password | (Password only) The password visitors must type. | Empty |
| Hide on Desktop | Hide at ≥ 1025 px wide. | Off |
| Hide on Tablet | Hide at 601–1024 px wide and at least 601 px tall. | Off |
| Hide on Mobile Portrait | Hide at ≤ 600 px wide, in portrait. | Off |
| Hide on Mobile Landscape | Hide at ≤ 1024 px wide, ≤ 600 px tall, in landscape. | Off |
The four bands don't overlap
The height conditions are what separate a phone held sideways (wide but short) from a tablet in landscape (wide and tall). Without them, "Hide on Tablet" would also hide every phone turned on its side.
In the editor a hidden gallery is dimmed and outlined rather than removed, with a badge naming which devices it's hidden on — otherwise you couldn't select it to switch the option back off.
Advanced
| Control | What it does |
|---|---|
| Additional CSS Class(es) | Extra classes on the gallery wrapper. |
| Additional CSS ID | An id on the gallery wrapper. |
There's no CSS box here, on purpose
Use these two as hooks and write the rules in Appearance → Customize → Additional CSS, which loads after every plugin stylesheet. Why the plugin ships no raw-CSS field →
Which panels each layout shows
| Panel | Justified · Grid · Masonry · Metro · Staggered | Thumbnails | Perspective |
|---|---|---|---|
| Layout Settings | ✅ | ✅ (its own Settings / Style tabs) | ✅ (its own set) |
| Horizontal / Vertical Gap | ✅ | ❌ (one Thumbnails Gap instead) | ✅ (in its own order) |
| Order · Ajax Pagination switch | ✅ | ❌ | ❌ |
| Image & Video Settings | ✅ | ✅ | ✅ |
| Content Settings | ✅ (Classic or Overlay) | ✅ (Overlay only) | ✅ (Overlay only) |
| Image Click Action | ✅ | ❌ | ✅ |
| Ajax Pagination panel | ✅ (when switched on) | ❌ | ❌ |
| Image Filter & Search | ✅ | ❌ | ❌ |
| Motion Effects | ✅ | ❌ | ❌ |
| Advanced Settings | ✅ | ✅ | ✅ |
Thumbnails is a slider and Perspective is a 3D marquee — each builds its own item model, so filtering, paging and per-item entrance animations have nothing to act on. Rather than showing controls that save and do nothing, both layouts hide them.
Gallery Info
Directly under the block card, above every panel:
- A Documentation link straight to this page.
- On a saved gallery, the gallery's id and its permanent shortcode, with a copy button. The same pair also appears in the editor's Post tab, so it's visible the moment the editor opens.