Media module

Gallery block

Images in a grid, masonry, carousel or slider — with a lightbox, captions, hover effects and a filter bar built from image tags.

Overview

The Gallery shows a set of images in four layouts: Grid (equal tiles), Masonry (natural heights, Pinterest-style), Carousel (several per view, swipeable) and Slider (one large image at a time). Clicking an image can open an accessible lightbox with previous/next navigation. You can tag images (“Kitchen”, “Bathroom”) and show filter buttons so visitors can narrow the gallery down.

At a glance

Block name: wpbb/gallery
Module: Media
Find it by searching: Gallery
Loads JavaScript on the site: Only for the lightbox, filter buttons or Carousel/Slider layouts

When and why to use it

Portfolios and project photos.
Product or venue galleries with a lightbox.
Filterable galleries by category.

Example scenarios

Interior designer: Masonry, Lightbox, filter buttons for “Kitchen”, “Living room”, “Bathroom”.
Hotel: Slider of 8 photos with captions over the image and autoplay.

See it in action

These are live examples: real Gallery blocks rendered by WordPress with the plugin’s own styles and scripts. Use the buttons to see how they adapt to tablet and phone screens.

Grid with lightbox and filter

Open in a new tab

How to add the Gallery block

Open the editor. In your WordPress dashboard go to Pages (or Posts) and click the page you want to edit, or click Add New. For headers, footers and templates, use Appearance → Editor (block themes).
Add a new block. Click the blue + (Block Inserter) button in the top-left corner, or the small + that appears where you want the block. You can also type / on an empty line.
Search for the block. Type Gallery in the search field. Brigade Blocks appear in the Brigade Blocks category and show the coral block icon.
Insert it. Click Gallery in the results. The block appears with a placeholder to upload images or pick them from the Media Library.
Configure the content. Upload images or click Media Library and select several. Click an image in the block to edit its alt text, caption and filter tags in the Selected image panel. Use Edit gallery in the toolbar to add, remove or reorder images.
Customise the design. Switch to the Styles tab (half-filled circle icon) to change colours, spacing, borders and more — see Design & styling.
Save or publish. Click Save draft to keep working later, Preview to check it, or Publish / Update to make it live.

Content settings

You set up this block in two places: on the block itself in the editor, and in the Settings tab (gear icon) of the sidebar on the right. Every option is listed below, with its default value.

On the block (in the editor canvas)

Images

What it does: The pictures in the gallery.
What to enter or choose: Several images from the Media Library or new uploads.
Default: None selected
How to use it: Use the placeholder at first, then Edit gallery in the toolbar.
When to use it: Always — an empty gallery is not shown.
Example: 12 project photos.
Result: The images appear in the chosen layout.

Selecting an image

What it does: Clicking an image in the block selects it and opens the Selected image panel in the sidebar.
What to enter or choose: Click any image (or its “Edit image N” button).
How to use it: Click the text in the block on the page and type. Use the block toolbar for bold, italic and links.
When to use it: To edit one image’s details.
Example: —
Result: The panel shows that image’s settings.

Settings panel: Layout

Layout

What it does: How images are arranged.
What to enter or choose: One of: Grid, Masonry, Carousel, Slider (one at a time).
Default: Grid
How to use it: Open the dropdown and pick an option.
When to use it: Grid for tidy tiles; Masonry for mixed portrait/landscape; Carousel/Slider to save space.
Example: Masonry for a photography portfolio.
Result: Masonry switches to original image shapes; Slider starts with 16:9 images and captions over them (only if you had not changed those settings).

Columns (desktop)Shown when Layout is not SliderDesktop

What it does: Items per row on large screens.
What to enter or choose: A number from 1 to 8.
Default: 3
How to use it: Drag the slider, or type a number in the box next to it.
When to use it: Always.
Example: 3.
Result: Items resize to fit.

Columns (tablet)Shown when Layout is not SliderTablet

What it does: Items per row below 1024px.
What to enter or choose: A number from 1 to 6.
Default: 2
How to use it: Drag the slider, or type a number in the box next to it.
When to use it: Always.
Example: 2.
Result: Applies up to 1023px wide.

Columns (mobile)Shown when Layout is not SliderMobile

What it does: Items per row below 600px.
What to enter or choose: A number from 1 to 4.
Default: 1
How to use it: Drag the slider, or type a number in the box next to it.
When to use it: Always.
Example: 1.
Result: Applies up to 599px wide.

Gap (px)

What it does: Space between items.
What to enter or choose: A number from 0 to 80 (px).
Default: 16 px
How to use it: Drag the slider, or type a number in the box next to it.
When to use it: Always optional.
Example: 8 for a tight mosaic.
Result: Items move closer or further apart.

Image ratioShown when Layout is not Masonry

What it does: The tile shape.
What to enter or choose: One of: Original, 1:1, 4:3, 3:2, 16:9, 3:4.
Default: 4:3
How to use it: Open the dropdown and pick an option.
When to use it: Keep tiles aligned.
Example: 1:1 for an Instagram look.
Result: Images are cropped to that shape.

Resolution

What it does: Which file size is shown in the gallery.
What to enter or choose: One of your site’s image sizes.
Default: large
How to use it: Open the dropdown and pick an option.
When to use it: Smaller for more columns.
Example: Medium for 6 columns.
Result: The lightbox always opens the full-size image.

Settings panel: Images

Click opens

What it does: What happens when an image is clicked.
What to enter or choose: One of: Lightbox, Image file, Nothing.
Default: Lightbox
How to use it: Open the dropdown and pick an option.
When to use it: Lightbox for browsing; Nothing for decorative galleries.
Example: Lightbox.
Result: Lightbox: images open in an overlay with previous/next and a counter; Image file: opens the full image in the browser.

Captions

What it does: Where captions appear.
What to enter or choose: One of: Hidden, Below the image, Over the image.
Default: Hidden
How to use it: Open the dropdown and pick an option.
When to use it: When captions add information.
Example: Over the image for a slider.
Result: Captions come from each image’s Caption field.

Hover effect

What it does: An effect when the pointer is over an image.
What to enter or choose: One of: Zoom, Lift, Grayscale to colour, None.
Default: Zoom
How to use it: Open the dropdown and pick an option.
When to use it: For clickable images.
Example: Grayscale to colour for a calm portfolio.
Result: The effect runs on hover.

Not available for the Carousel and Slider layouts.

Settings panel: Carousel

Only shown for the Carousel and Slider layouts. The panel starts closed.

Arrows

What it does: Shows previous/next arrow buttons.
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Keep on for desktop visitors.
Example: On.
Result: Arrows at the sides.

Dots

What it does: Shows a dot per page below the slides.
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: To show how many slides there are.
Example: On.
Result: Clickable dots.

Loop

What it does: After the last slide, continues from the first.
What to enter or choose: On or off.
Default: On
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Usually on.
Example: On.
Result: Arrows never become disabled.

Autoplay

What it does: Advances slides automatically.
What to enter or choose: On or off.
Default: Off
How to use it: Click the switch to turn it on (blue) or off.
When to use it: Use sparingly — moving content distracts.
Example: On for a hero slider.
Result: Pauses on hover and focus, shows a pause button, and never runs for visitors who prefer reduced motion.

Delay (seconds)Shown when Autoplay is on

What it does: Time each slide stays.
What to enter or choose: A number from 2 to 15 (s).
Default: 5 seconds
How to use it: Drag the slider, or type a number in the box next to it.
When to use it: Longer for slides with text.
Example: 6.
Result: Slower or faster autoplay.

Settings panel: Selected image (N)

Appears after you click an image in the block. Settings here apply to that one image.

Alternative text

What it does: Describes the image for people who cannot see it.
What to enter or choose: A short description, or empty if purely decorative.
How to use it: Type into the text field. Changes appear in the preview right away.
When to use it: For every meaningful image.
Example: “Open-plan kitchen with oak cabinets.”
Result: Used as the image’s alt text.

Caption

What it does: The image caption.
What to enter or choose: A short sentence.
How to use it: Type into the text field. Changes appear in the preview right away.
When to use it: When Captions are shown.
Example: “Villa Serena, 2025.”
Result: Shown below or over the image, and in the lightbox.

Filter tags

What it does: Tags used by the filter buttons.
What to enter or choose: Comma-separated words.
How to use it: Type into the text field. Changes appear in the preview right away.
When to use it: With the filter.
Example: “Interior, Kitchen”.
Result: The image appears under each of its tags.

Move earlier / Move later / Remove

What it does: Reorders or removes the selected image.
What to enter or choose: Click a button.
How to use it: Select the block; the button is in the toolbar that appears above it.
When to use it: Anytime.
Example: Move the best photo first.
Result: The gallery updates.

Design & styling

Select the block, open the Styles tab in the settings sidebar (the half-filled circle icon next to the gear) and use the three pickers at the top of the Style panel:

Element — which part of the block to style.
State — Normal, or a state such as Hover (only the states the part supports are offered).
Device — Desktop, Tablet or Mobile, for values that can differ per screen size.

Only panels that make sense for the chosen part and state are shown. The full meaning of every control is in the Styling Controls guide; below is exactly what Gallery offers.

Element: Image selected first

Each image frame. Hover state (image hovered).

Styles-tab controls for “Image”
Panel	Control	Per device	Available in states
Border	Border type	—	Normal, Hover
	Border	—	Normal, Hover
	Radius	Yes	Normal
Box Shadow	Remove shadow	—	Normal, Hover
Box Shadow	Shadow layers	—	Normal, Hover
Effects	Opacity (%)	Yes	Normal, Hover

States for this part:

Hover — When the mouse pointer is over the whole block — so this part changes as soon as visitors point at the block.

Element: Block

The whole gallery.

Styles-tab controls for “Block”
Panel	Control	Per device	Available in states
Background	Type	—	Normal
	Color / Gradient	—	Normal
	Image	—	Normal
Border	Border type	—	Normal
	Border	—	Normal
	Radius	Yes	Normal
Box Shadow	Remove shadow	—	Normal
Box Shadow	Shadow layers	—	Normal
Spacing	Margin	Yes	Normal
Spacing	Padding	Yes	Normal
Sizing	Width	Yes	Normal
	Max width	Yes	Normal
	Height	Yes	Normal
	Min width / Min height / Max height	Yes	Normal
	Block alignment	Yes	Normal
Position	Position	Yes	Normal
	Top / Right / Bottom / Left	Yes	Normal
	Z-index	Yes	Normal
	Overflow	Yes	Normal
Transform	Move X / Move Y	—	Normal
	Scale X / Scale Y	—	Normal
	Rotate (°), Rotate X (°), Rotate Y (°)	—	Normal
	Skew X (°) / Skew Y (°)	—	Normal
Effects	Opacity (%)	Yes	Normal
	State transition (ms)	—	Normal
	Timing	—	Normal
Visibility	Show on Desktop / Tablet / Mobile	—	Normal

States: Normal only.

Element: Caption

Captions.

Styles-tab controls for “Caption”
Panel	Control	Per device	Available in states
Typography	Font family	—	Normal
	Font size	Yes	Normal
	Weight	—	Normal
	Style	—	Normal
	Line height	Yes	Normal
	Letter spacing	Yes	Normal
	Letter case	—	Normal
	Alignment	Yes	Normal
	Decoration	—	Normal
Colors	Text	—	Normal
Background	Type	—	Normal
	Color / Gradient	—	Normal
	Image	—	Normal
Spacing	Padding	Yes	Normal

States: Normal only.

Element: Filter buttons

Filter buttons. Hover, Focus and Active (selected filter).

Styles-tab controls for “Filter buttons”
Panel	Control	Per device	Available in states
Typography	Font family	—	Normal
	Font size	Yes	Normal
	Weight	—	Normal
	Style	—	Normal
	Line height	Yes	Normal
	Letter spacing	Yes	Normal
	Letter case	—	Normal
	Alignment	Yes	Normal
	Decoration	—	Normal, Hover, Focus, Active
Colors	Text	—	Normal, Hover, Focus, Active
Background	Type	—	Normal, Hover, Focus, Active
	Color / Gradient	—	Normal, Hover, Focus, Active
	Image	—	Normal
Border	Border type	—	Normal, Hover, Focus, Active
	Border	—	Normal, Hover, Focus, Active
	Radius	Yes	Normal
	Focus indicator	—	Focus
Box Shadow	Remove shadow	—	Normal, Hover, Focus, Active
Box Shadow	Shadow layers	—	Normal, Hover, Focus, Active
Spacing	Padding	Yes	Normal
Sizing	Width	Yes	Normal
	Max width	Yes	Normal
	Height	Yes	Normal
	Min width / Min height / Max height	Yes	Normal
Effects	Opacity (%)	Yes	Normal, Hover, Focus, Active

States for this part:

Hover — When the mouse pointer is over it. (Touch screens have no hover; they show the normal style.)
Focus — When it has keyboard focus — reached with the Tab key. Mouse clicks usually do not show focus styles.
Active — Applies to the selected filter button.

Element: Carousel arrows

Carousel arrows. Hover and Focus.

Styles-tab controls for “Carousel arrows”
Panel	Control	Per device	Available in states
Colors	Text	—	Normal, Hover, Focus
Background	Type	—	Normal, Hover, Focus
	Color / Gradient	—	Normal, Hover, Focus
	Image	—	Normal
Border	Border type	—	Normal, Hover, Focus
	Border	—	Normal, Hover, Focus
	Radius	Yes	Normal
Box Shadow	Remove shadow	—	Normal, Hover, Focus
Box Shadow	Shadow layers	—	Normal, Hover, Focus
Sizing	Width	Yes	Normal
	Max width	Yes	Normal
	Height	Yes	Normal
	Min width / Min height / Max height	Yes	Normal

States for this part:

Hover — When the mouse pointer is over it. (Touch screens have no hover; they show the normal style.)
Focus — When it has keyboard focus — reached with the Tab key. Mouse clicks usually do not show focus styles.

Element: Carousel dots

Carousel dots. Active = current slide.

Styles-tab controls for “Carousel dots”
Panel	Control	Per device	Available in states
Background	Type	—	Normal, Active
	Color / Gradient	—	Normal, Active
	Image	—	Normal
Border	Radius	Yes	Normal
Sizing	Width	Yes	Normal
	Max width	Yes	Normal
	Height	Yes	Normal
	Min width / Min height / Max height	Yes	Normal

States for this part:

Active — Applies to the current slide’s dot.

Responsive settings

Brigade Blocks uses three screen sizes: Desktop (wider than 1023px), Tablet (600–1023px) and Mobile (599px and narrower). Tablet and Mobile values are optional: when empty, the value of the next larger screen is used.

In the Styles tab, pick the Device first; these controls can then have a different value for that screen size: Radius, Opacity (%), Margin, Padding, Width, Max width, Height, Min width / Min height / Max height, Block alignment, Position, Top / Right / Bottom / Left, Z-index, Overflow, Font size, Line height, Letter spacing, Alignment.

The Visibility panel (Styles tab, Normal state) can hide the block entirely on Desktop, Tablet or Mobile.

Advanced options

HTML anchor (Advanced section of the Settings tab) — a unique name such as pricing, so you can link straight to this block with #pricing at the end of the page address (for example from a menu).
Additional CSS class(es) (Advanced section) — for custom CSS from your theme or the Site Editor. Separate several classes with spaces.
Custom attributes (Advanced section) — add data-*, title, aria-label, aria-describedby, lang or dir attributes. See Custom attributes.
State transition (Styles tab → Effects, Normal state) — how smoothly hover and focus styles animate.
Width alignment (block toolbar) — Wide width, Full width, when your theme supports them.

How it works on your site

Images are regular responsive images with srcset. Each image is a normal link to the full-size file, so it works without JavaScript; with JavaScript the lightbox opens instead. The lightbox and carousel scripts load only when used.

Accessibility

Lightbox: a native dialog — focus stays inside, Esc closes it and returns focus to the image; arrow keys and swipe move between images.
Images without alternative text are treated as decorative.
Filter buttons announce which one is pressed.
Filtered-out images are skipped in the lightbox.

Tips and best practices

Upload images of similar size and orientation for tidy grids — or use Masonry.
Keep tags short and few (3–6) so the filter bar stays readable.

Limitations and notes

Carousel and Slider layouts have no filter bar.
Images must come from the Media Library.

Overview

At a glance

When and why to use it

Example scenarios

See it in action

How to add the Gallery block

Content settings

On the block (in the editor canvas)

Images

Selecting an image

Block toolbar

Edit gallery

Settings panel: Layout

Layout

Columns (desktop)Shown when Layout is not SliderDesktop

Columns (tablet)Shown when Layout is not SliderTablet

Columns (mobile)Shown when Layout is not SliderMobile

Gap (px)

Image ratioShown when Layout is not Masonry

Resolution

Settings panel: Images

Click opens

Captions

Hover effect

Settings panel: Filter

Show filter buttons

“All” button labelShown when Show filter buttons is on

Settings panel: Carousel

Arrows

Dots

Loop

Autoplay

Delay (seconds)Shown when Autoplay is on

Settings panel: Selected image (N)

Alternative text

Caption

Filter tags

Move earlier / Move later / Remove

Design & styling

Element: Image selected first

Element: Block

Element: Caption

Element: Filter buttons

Element: Carousel arrows

Element: Carousel dots

Responsive settings

Advanced options

How it works on your site

Accessibility

Tips and best practices

Limitations and notes