Gallery Block

The Gallery block lets you add multiple images to a page and display them together in a structured image gallery. It’s useful when a group of images should be viewed as a set, such as event photos, portfolio examples, product imagery, or supporting visuals for a story.

Use the Gallery block when you want to show a collection of related images together.

It’s ideal for:

  • Displaying multiple photos in a clean, organized layout
  • Keeping related images grouped in one section
  • Controlling gallery-wide layout, image size, and display behavior
  • Creating a more visual page experience without manually arranging individual Image blocks

Galleries work best when the images share a clear relationship. If an image needs to stand alone or support one specific piece of nearby text, the Image block may be a better choice.

How to use the block

Start by adding the Gallery block to the page. Learn how to add blocks.

The Gallery block acts as a parent block that contains multiple Image blocks. Editors can manage the gallery as a whole, while still selecting individual images when image-specific edits are needed. Gallery settings include controls for columns, image resolution, cropping, random order, aspect ratio, and gallery-wide link behavior.

Once the block is added, editors typically:

  • Open the Media Library to choose existing images or upload new ones
  • Select multiple images for the gallery
  • Review and arrange images before inserting the gallery
  • Adjust gallery settings in the block toolbar and block settings sidebar
  • Edit individual Image blocks inside the gallery when needed

After adding the Gallery block, you can choose Upload to select files from your computer or Open Media Library to choose images from the Media Library. The Media Library also allows new images to be uploaded.

After selecting multiple images, click Create a new gallery. This opens the Edit gallery screen, where you can review the selected images before inserting them into the page.

From the Edit gallery screen, editors can:

  • Add a caption to each image
  • Remove images using the X icon
  • Reorder images by dragging and dropping them
  • Use Add to gallery in the sidebar to select additional images from the Media Library
  • Cancel or continue editing before inserting the gallery

When the gallery is ready, click Insert gallery to add it to the page.

Once inserted, the gallery is structured as a Gallery block with multiple nested Image blocks inside it.

Block toolbar

The block toolbar appears above the Gallery block when the Gallery block is selected.

Available options

  • Link options: Controls whether images in the gallery link somewhere when clicked. Options include attachment pages, media files, enlarge on click, or none. The default is None. In most cases, use None or Enlarge on click. WordPress describes Enlarge on click as opening the image in a larger dialog on the same page.
  • Caption: Adds a caption for the entire gallery. This is different from captions added to individual images.
  • Block width: Adjusts how wide the gallery appears within the page layout.
  • Add: Adds more images to the gallery. You can upload new images or select existing images from the Media Library.

Use toolbar options to manage the gallery as a whole. To edit an individual image, select that specific Image block inside the gallery.

Block settings

Block settings appear in the right sidebar while the Gallery block is selected.

Columns

Controls the number of columns used to display images in the gallery. Use this setting to adjust the overall gallery layout. Fewer columns create larger images. More columns create a tighter grid.

The available number of columns depends on the number of images in the gallery. For example, a gallery with 4 images can only use up to 4 columns.

Resolution

Controls the image size used in the gallery. Available image sizes may vary, but common options include Thumbnail, Medium, Large, and Full Size. Use Medium when you want to help keep page size smaller. Use Full Size carefully, and only when images have been appropriately resized before upload.

Large image files can slow down the page. If using Full Size, avoid uploading extremely large files directly from a camera or design export.

Crop images to fit

Crops images so they appear at a consistent size within the gallery. This is helpful when images have different orientations or dimensions and you want the gallery to feel more even. Because cropping can hide parts of an image, preview the gallery to confirm important visual details are still visible.

Randomize order

Displays gallery images in a random order each time the page is loaded. This can be helpful when image order does not matter and you want the page to feel a little different each time someone visits.

Random order affects the published page. In the editor, images continue to appear in their original order.

Aspect ratio

Applies the same dimensions to all images in the gallery. Use this when you want a consistent image shape across the full gallery. Aspect ratio can help create a cleaner grid, especially when images are uploaded in different sizes or orientations.

Block styles

In Block Settings, the Styles tab includes visual controls for the Gallery block.

Dimensions

Padding: Adds space inside the gallery container

Margin: Adds space outside the gallery container

Managing individual images

After a gallery is added, each image inside the gallery is an individual Image block nested inside the Gallery block.

Select an individual Image block when you need to manage settings for that specific image. For detailed guidance, see the Image block documentation.

Editors will typically leave individual image settings unchanged. When changes are needed, apply the same approach consistently to each image in the gallery so the layout feels intentional.

Reordering images from the image toolbar

When an individual image inside the gallery is selected, the Image block toolbar includes move controls.

Use Move left and Move right to reposition images within the gallery. WordPress also documents these toolbar controls as the way to rearrange individual images after the gallery has been inserted.

Accessibility and content structure

The Gallery block can improve page structure by keeping related images grouped together. The most important accessibility work for editors happens at the image level.

To keep galleries accessible:

  • Use images that support the page content
  • Add helpful alt text to individual images when the image communicates meaningful information
  • Leave alt text empty only when an image is decorative
  • Use captions when they add useful context
  • Avoid relying on image order alone to communicate important meaning, especially if Randomize order is enabled

Gallery-wide captions describe the full collection. Individual image captions describe specific images. Use whichever level of captioning best supports the reader.

Tips for editors

Use galleries for related images

A gallery should feel like a set. Avoid using it to place unrelated images together just because they need to appear near each other.

Choose link behavior intentionally

Most galleries should use None or Enlarge on click. Linking to attachment pages or media files can create a less focused experience unless there is a specific reason to send users there.

Keep image sizes manageable

Large image files can slow down the page. Resize images before uploading when possible, and use Medium resolution when a smaller image size works well for the layout.

Be consistent with individual image edits

If you adjust settings for one nested Image block, consider whether the same change should apply to the rest of the images in the gallery. Consistency helps the gallery feel polished and easier to scan.

  1. WordPress.org Gallery Block documentation — please note that your block may have customizations affecting functionality, appearance, or settings.