Gallery Block

Go back to the list of Blocks

The Gallery block allows you to easily add multiple photos and automatically arrange them in a gallery. You can control the number of columns and the size of the images in the gallery.

The Gallery block can be added to a page by clicking on the (+) Block Inserter icon and selecting the Gallery block.

Image showing the Quick Inserter with gallery in the search field.
Adding the gallery block

Alternatively, you can type /gallery and press enter.

Image of the slash inserter with the gallery block listed.
Adding the gallery block with /gallery shortcut

Detailed instructions on adding blocks can be found here.

Block Toolbar

Each block has its own block-specific controls that allow you to manipulate the block right in the editor.

The gallery block has a toolbar for the individual images as well as a toolbar for the entire gallery block. 

Gallery block toolbar options

Top ↑

The main options in the Gallery Block Toolbar are:

  • Transform to
  • Block moving handles
  • Change alignment
  • Add button
  • More options

Transform to

You can transform or change the block to another block including the Group block, Image block, and Column block.

When you change the block type to the Image block, every image in your gallery will be converted into a single image block.

Block moving handles

The block-moving handles allow you to move the block up and down the editor. Use the six dots icon to drag and drop the Gallery block and place it anywhere on the page. Alternatively, click on the up and down arrows to move the block up or down.

Change alignment

  • Align left – Make the block align-center
  • Align center – Make the block alignment centered
  • Align right – Make the block align-right
  • Wide width – Increase the width of the block beyond the content size
  • Full width – Extend the block to cover the full width of the screen.

“Wide width” and “Full width” alignment options are only available if they are enabled in your theme.

Add images

The Add button in the gallery block lets you add images to the gallery. You have two options to add images to the gallery blockOpen Media Library and Upload.

Upload allows you to upload a new image or multiple images to the Gallery block and to your media library. Media Library lets you select from previously uploaded images in your Media Library.

You can also drag & drop multiple images at the same time from your explorer or finder window into the gallery block.

More options

More options toolbar

Hide more settings

The Hide more settings option hides (or shows) the Block Setting panel in the editor’s sidebar.

Copy

Copy can be used to copy a selected block and then you can paste it wherever you want in the editor.

Duplicate

Duplicate can be used to duplicate selected block.

Insert before

Insert a new block before the selected block(s).

Insert after

Insert a new block after the selected block(s).

Move to

If you select Move To, you will get a blue line inside your content, you can then use the arrows to move that line, up and down to where you want the selected content to be moved into, hitting return on your keyboard at that point moves the block to that position.

Lock 

Lets you prevent users from moving or deleting the selected block. A pop-up window will appear to set the block locking attribute to the selected block. You can opt to disable movement, prevent removal, or both for the selected block.

Add to Reusable blocks

Using the Add to Reusable blocks option lets you add the selected block to a list of reusable blocks, so you can use them on other posts or pages as well.

Group

Select the Group option if you want to create a group of blocks and treat them as a unit. You can for instance add a common background color or other blocks to the group.

Remove Gallery

With the Remove Gallery option, you can delete the selected block from your content.

Top ↑

Move images

After you add images to the gallery block, you can change the order of images in the gallery. Click on an image and in the block toolbar use the move left and move right arrow handles to arrange the images as you like.

Moving images in your gallery

Add a link to an image

To add a link to an image, click the link icon in the block toolbar for the selected image. You can paste a URL for the link, type in the text field to search for a page. You can also link to the Media file of the image or the Attachment Page for the image.

You can change the link settings by clicking the down arrow in the top right corner. You can choose to open the link in a new tab, add CSS class for the link and link rel attribute, if needed.

After you add a link to the image, you can click the link icon in the block toolbar and choose the pen icon to edit the link or the X icon to delete the link.

Crop an image

Here’s a video showing how you can crop an image in the gallery, zoom in, rotate and crop by keeping the aspect ratio of the selected image.

Apply duotone filters to an image

Here’s a video showing how you can set different image filters, either based on the image filters your theme provides or a custom one you set:

Replace an image

You can replace images in your gallery with the Replace button in the block toolbar of the selected image. This will allow you to upload a new image to the media library or select another image from your library.

Image showing the replace toolbar.
Replacing images in your gallery

Remove an image

To remove an image from your gallery, select the image in the gallery and either click delete on your keyboard or select the three-dot menu on the block toolbar of the selected image and select “Remove Image”.

More options

More options toolbar

Hide more settings

The Hide more settings option hides (or shows) the Block Setting panel in the editor’s sidebar.

Select parent block

The select parent block option will move you to the parent block that contains the Gallery block.

Copy

Copy can be used to copy a selected block and then you can paste it wherever you want in the editor.

Duplicate

Duplicate can be used to duplicate selected block.

Move to

If you select Move To, you will get a blue line inside your content, you can then use the arrows to move that line, up and down to where you want the selected content to be moved into, hitting return on your keyboard at that point moves the block to that position.

Edit as HTML

The Edit as HTML option allows you to modify the HTML code of the image block.

Lock 

Lets you prevent users from moving or deleting the selected block. A pop-up window will appear to set the block locking attribute to the selected block. You can opt to disable movement, prevent removal, or both for the selected block.

Add to Reusable blocks

Using the Add to Reusable blocks option lets you add the selected block to a list of reusable blocks, so you can use them on other posts or pages as well.

Remove Image

With the Remove Image option, you can delete the selected image from the gallery block.

Top ↑

Adding captions

Adding a caption for images

You can caption your images individually by editing the “Add caption” text with the image.

Adding a caption for the gallery

You can also caption the entire gallery by clicking on the Gallery block and replacing the text for Write gallery caption at the bottom of the gallery.

Top ↑

Block Settings

Every block has specific options in the editor sidebar in addition to the options found in the block toolbar. If you do not see the sidebar, simply click the ‘cog’ icon.

Cog icon to display the Block sidebar

Top ↑

Gallery settings

Columns

You can choose how many columns your Gallery block can have.

Select between 1 column and 8 columns. Keep in mind that you can only select as many columns as you have images.

This means that if you add 4 images, you’ll be given the option for a maximum of 4 columns. This number will increase as you add more images until you reach the maximum of 8. Even if you add more images to the Gallery, you will not be able to add more than 8 columns.

Your images will automatically arrange themselves to look good no matter how many columns you select. Try changing the setting and see what you like best.

To change the setting you can either manually enter the number of columns you want or visually change the number by using the slider to drag the number up and down.

Crop images

You can select whether or not you’d like all of your images to be cropped in your Gallery block.

Cropping images in your gallery

This option is useful if you have images of varying sizes and shapes. Cropping them will make the images in each row of the gallery the same size. You can toggle this option on and off to see which way you prefer.

Link to

You have 3 options for linking the images in your gallery: Attachment Page, Media File, and None. This determines what happens when your visitors click on the images in your gallery. You can also add custom links for each image from the block toolbar of the selected image.

  • Attachment page: Selecting this option will link the image to its WordPress media attachment page. This is an informational page about your image, which includes the image, the caption, the image description, and a comment field.
  • Media file: Selecting this option will link the image to the image file in the original size in a new browser window.
  • None: Selecting this option will not link the image to anything.

Image sizes

The Image Size setting allows you to set all the images to the size you choose.

  • Thumbnail: Displays a small thumbnail-sized version of your image on the page/post. Note, by default the Thumbnail size is a square, so some cropping of your original image may occur.
  • Medium: Displays a medium-sized version of your image on the page/post. This is a good size to use with Left/Right alignments, as it leaves sufficient space for legible text to either side.
  • Large: Displays a large-sized version of your image on the page/post. Note: WordPress will determine the width of the content column of your theme, and display the largest possible image for that space.
  • Full Size: Displays a full-sized version of your image on the page/post. Note: WordPress will determine the width of the content column of your theme, and display the largest possible image for that space. If your original image is larger than this column width, the full size of the image may not be displayed.

Note: For these images sizes to work, your theme needs to support them.

Dimensions settings

Click on the 3-dot icon in the right top corner in the Dimensions settings to explore all the Dimensions settings for the gallery block. You can click ‘Reset all’ to reset all the Dimension settings changes.

For the gallery block, you can adjust the block spacing. Block spacing is a very useful design tool for the gallery block. It lets you create spacing between the images in the gallery block. You can adjust the spacing in PX, %, EM, REM, VH and VW.

Here is a video showing how the block spacing works in the gallery block.

Advanced settings

The “Advanced” tab lets you add HTML anchor and CSS class(es) to your block.

HTML anchor allows you to do “page jumping” to the gallery. Page jumping, also sometimes referred to as anchor links, is where you click a link and instantly get moved somewhere further up or down a long page.

To enable this, you put an HTML anchor in the Advanced settings in the gallery block. You can then create a link to this anchor anywhere on the page and it scrolls to the gallery block.

The advanced tab also lets you add a CSS class to your block, allowing you to write custom CSS and style the block as you see fit.

Top ↑

Styles settings

You can vary the styles of the images in the gallery block by choosing the Styles settings. You have two different style options in the block sidebar, when you select an image.

Image settings

Image showing where one can find alternative text fields for each image in a gallery block.

For each image in the gallery, add alternative text to help with accessibility. ALT text can describe the purpose of the image. Leave the ALT text field empty if the image is purely decorative.

Image sizes

The Image Size setting allows you to set the image size for individual images in the gallery. You can choose between Thumbnail, Medium, Large and Full size.

Note: For these images sizes to work, your theme needs to support them.

Border settings

Border settings let you define custom radius value for each image in the gallery block. You can type in a value in the Radius text field or use the slider to adjust the value for the border radius.

Border settings for the individual button in the buttons block

You can define the border radius value using one of the six available unit options.

Border units for the individual button in the buttons block

You can set the same value for border radius for all the four corners of the image. To set different values for each of the corners, click the Link icon.

Setting separate border radius values  for the individual button in the buttons block

Click the 3-dot icon in the top right corner in the Border settings panel and click ‘Reset all’ to rest all the border settings changes you made.

Advanced settings

The advanced settings for each image has a Title attribute, HTML anchor and CSS class fields.

The Title attribute field is designed to describe the role of the image on your page. Many devices and browsers don’t display this text.

HTML anchor allows you to do “page jumping” to that specific image. Page jumping, also sometimes referred to as anchor links, is where you click a link and instantly get moved somewhere further up or down a long page.

To enable this, you put an HTML Anchor in your photo, and create a link that jumps to the anchor.

The advanced tab also lets you add a CSS class to your block, allowing you to write custom CSS and style the image as you choose.

Note: Based on which style you choose for the image block in the Styles settings, WordPress automatically adds a CSS class to the image block under Additional CSS class(es). You can add additional classes with spaces.

Top ↑

Changelog

  • Updated 2022-08-21
    • Added 6.0 screenshots and videos.
    • Updated block toolbar with Add button and replace the info with the updated process for adding images to the gallery.
    • Reordered the info to separate for the block toolbar and block sidebar.
    • Adding Dimensions to the block settings with video.
    • Updating the blosk settings for images.
    • Adding details for image customizations with content, screenshots and video.
    • Added ALT tags for images.
  • Updated 2021-12-21
    • Updated all screenshots for 5.9 with higher resolution.
    • Added in a context related to the refactoring.
  • Updated 2021-02-02
    • Updated the 5.5 video with 5.6 gifs
    • Updated all screenshots with 5.6
    • Added details to Advanced block settings options
    • Updated out-of-date contents
  • Updated 2020-10-05
    • Updated the video
  • Updated 2020-09-14
    • Updated 5.5 screenshots
    • Updated Block toolbar new features
    • Updated Block settings new features
  • Updated 2020-06-18
    • Added ‘Link back to blocks’ to the top of the page
  • Updated 2020-04-24
    • Added Drag & Drop multiple images to the Gallery block
    • Added video to change the background color as group block
    • Added updated UI displays for WordPress 5.4
    • Added “More Options” to the Block Toolbar section and updated the existing once to fit other block descriptions.
    • Reorganized the post into 3 sections: How to add gallery and images, Block Toolbar and Block Settings.
    • Converted all reusable blocks to regular blocks.
  • Created 2019-03-07

Was this article helpful? How could it be improved?