Title: Gallery block Author: Sophie - a11n Published: March 7, 2019 Last modified: March 17, 2026 --- # Gallery block ## In this article * [Add a Gallery block](https://wordpress.org/documentation/article/gallery-block/?output_format=md#add-a-gallery-block) * [Block toolbar](https://wordpress.org/documentation/article/gallery-block/?output_format=md#block-toolbar) - [Transform to](https://wordpress.org/documentation/article/gallery-block/?output_format=md#transform-to) - [Block moving handles](https://wordpress.org/documentation/article/gallery-block/?output_format=md#block-moving-handles) - [Change alignment](https://wordpress.org/documentation/article/gallery-block/?output_format=md#change-alignment) - [Link](https://wordpress.org/documentation/article/gallery-block/?output_format=md#link) - [Caption for the gallery](https://wordpress.org/documentation/article/gallery-block/?output_format=md#caption-for-the-gallery) - [Adding images](https://wordpress.org/documentation/article/gallery-block/?output_format=md#adding-images) - [Options](https://wordpress.org/documentation/article/gallery-block/?output_format=md#options) * [Block toolbar for images in the gallery](https://wordpress.org/documentation/article/gallery-block/?output_format=md#block-toolbar-for-images-in-the-gallery) - [Move images](https://wordpress.org/documentation/article/gallery-block/?output_format=md#move-images) * [Block settings](https://wordpress.org/documentation/article/gallery-block/?output_format=md#block-settings) - [Columns](https://wordpress.org/documentation/article/gallery-block/?output_format=md#columns) - [Resolution](https://wordpress.org/documentation/article/gallery-block/?output_format=md#resolution) - [Crop images to fit](https://wordpress.org/documentation/article/gallery-block/?output_format=md#crop-images-to-fit) - [Randomize order](https://wordpress.org/documentation/article/gallery-block/?output_format=md#randomize-order) - [Aspect ratio](https://wordpress.org/documentation/article/gallery-block/?output_format=md#aspect-ratio) - [Advanced settings](https://wordpress.org/documentation/article/gallery-block/?output_format=md#advanced-settings) * [Block style settings](https://wordpress.org/documentation/article/gallery-block/?output_format=md#block-style-settings) - [Color](https://wordpress.org/documentation/article/gallery-block/?output_format=md#color) - [Dimensions](https://wordpress.org/documentation/article/gallery-block/?output_format=md#dimensions) - [Border](https://wordpress.org/documentation/article/gallery-block/?output_format=md#border) * [Changelog](https://wordpress.org/documentation/article/gallery-block/?output_format=md#changelog) [ Back to top](https://wordpress.org/documentation/article/gallery-block/?output_format=md#wp--skip-link--target) [Go back to the list of Blocks](https://wordpress.org/documentation/article/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. ## 󠀁[Add a Gallery block](https://wordpress.org/documentation/article/gallery-block/?output_format=md#add-a-gallery-block)󠁿 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. ](https://wordpress. org/documentation/files/2021/12/Screen-Shot-2021-12-21-at-4.09.44-PM-1024x542.png) Adding the Gallery block Alternatively, you can type `/gallery` and press Enter. ![Image of the slash inserter with the gallery block listed.](https://wordpress. org/documentation/files/2021/12/Screen-Shot-2021-12-21-at-4.08.17-PM-1024x726.png) Adding the Gallery block with _/gallery_ shortcut [Detailed instructions on adding blocks](https://wordpress.org/documentation/article/adding-a-new-block/) ## 󠀁[Block toolbar](https://wordpress.org/documentation/article/gallery-block/?output_format=md#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.  ![Block editor toolbar showing image tools and formatting options, with a Replace button on the right.](https://wordpress.org/documentation/files/2019/03/2026-02- 15_12-20.jpg) Block editor toolbar showing image tools and formatting options, with a Replace button on the right. The main options in the Gallery block toolbar are: * Transform to * Block moving handles - Drag and drop - Move up and down * Change alignment * Link * Caption * Add button * More options ### 󠀁[Transform to](https://wordpress.org/documentation/article/gallery-block/?output_format=md#transform-to)󠁿 ![Block editor ‘Transform to’ menu open, showing options like Columns, Details, Group, and Image.](https://wordpress.org/documentation/files/2019/03/galler-block- transform-to.jpg) Block editor ‘Transform to’ menu open, showing options like Columns, Details, Group, and Image. You can transform or change the block to another block including the Group, Image, and Column blocks. 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](https://wordpress.org/documentation/article/gallery-block/?output_format=md#block-moving-handles)󠁿 ![Moving a gallery block](https://wordpress.org/documentation/files/2022/08/Screen- Shot-2022-08-20-at-10.16.08-AM.png) 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. [[[Get more information about moving a block within the editor.](https://wordpress.org/documentation/article/moving-blocks/) ### 󠀁[Change alignment](https://wordpress.org/documentation/article/gallery-block/?output_format=md#change-alignment)󠁿 ![Gallery block alignment and width](https://wordpress.org/documentation/files/2022/ 08/Screen-Shot-2022-08-20-at-10.16.28-AM.png) * **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. ### 󠀁[Link](https://wordpress.org/documentation/article/gallery-block/?output_format=md#link)󠁿 You can choose link options to apply to all images in your gallery. ![Gallery link options.](https://wordpress.org/documentation/files/2019/03/Screenshot- 2026-03-06-at-3.05.21-PM-1024x408.jpg) * **Link images to attachment page**s: Selecting this option will link the image to its WordPress media [attachment](https://wordpress.org/documentation/article/inserting-images-into-posts-and-pages/#step-4-attachment-details) page. This is an informational page about your image, which includes the image, the caption, the image description, and a comment field. * **Link images to media file**s: Selecting this option will link the image to the image file in the original size in a new browser window. * **Enlarge on click:** Selecting this option creates a link in the image that opens it to a bigger size, as a dialog on the same page, when clicked. This is called the lightbox effect and it’s useful when you want the viewer to have the chance to see a certain image with more details without needing too much space while reading the content. * **None**: Selecting this option will not link the image to anything. ### 󠀁[Caption for the gallery](https://wordpress.org/documentation/article/gallery-block/?output_format=md#caption-for-the-gallery)󠁿 You can add this by clicking on the caption icon on the block settings toolbar. ![Adding a caption to the gallery block](https://wordpress.org/documentation/files/ 2019/03/gallery-caption-1024x641.png) Adding a caption to the Gallery block ### 󠀁[Adding images](https://wordpress.org/documentation/article/gallery-block/?output_format=md#adding-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 block: **Open Media Library** and ** Upload**. ![Adding images to the gallery block](https://wordpress.org/documentation/files/ 2022/08/Screen-Shot-2022-08-20-at-10.16.45-AM.png) Adding images to the Gallery block The Upload option allows you to upload a new image or multiple images to the Gallery block and to your media library. The Media Library option lets you select from previously uploaded images in your Media Library. You can also drag and drop multiple images at the same time from your explorer or finder window into the Gallery block. Alternatively, you can open the main inserter panel on the editor and open the media tab. Then, you can drag and drop images from the media library and Openverse into the Gallery block. ### 󠀁[Options](https://wordpress.org/documentation/article/gallery-block/?output_format=md#options)󠁿 These controls give you the option to copy, duplicate, and edit your block as HTML. [[[Read about these and other settings.](https://wordpress.org/documentation/article/more-options/) ## 󠀁[Block toolbar for images in the gallery](https://wordpress.org/documentation/article/gallery-block/?output_format=md#block-toolbar-for-images-in-the-gallery)󠁿 You will see additional block toolbar controls when you select an individual photo inside a gallery. Some options such as Add text over image or Align may not be present or my not work as expected when an Image block is inside a Gallery block. ### 󠀁[Move images](https://wordpress.org/documentation/article/gallery-block/?output_format=md#move-images)󠁿 ![Move block toolbar for images inside a gallery](https://wordpress.org/documentation/ files/2019/03/move-image-block-Screenshot-2026-03-08-at-8.03.12-AM-1024x369.jpg) 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. [Learn about additional block settings on the Image block page.](https://wordpress.org/documentation/article/image-block/) ## 󠀁[Block settings](https://wordpress.org/documentation/article/gallery-block/?output_format=md#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, click on the **Settings button** next to the Save/Publish button. ![Settings button highlighted in the block editor](https://wordpress.org/documentation/ files/2019/03/block-settings-Screenshot-2026-03-08-at-8.13.56-AM-1.png) The settings available for the Gallery block are * Columns * Resolution * Crop images to fit * Randomize order * Aspect Ratio * Advanced ![Gallery block settins](https://wordpress.org/documentation/files/2019/03/Screenshot- 2026-03-08-at-8.25.43-AM-392x1024.jpg) ### 󠀁[Columns](https://wordpress.org/documentation/article/gallery-block/?output_format=md#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. ### 󠀁[Resolution](https://wordpress.org/documentation/article/gallery-block/?output_format=md#resolution)󠁿 * **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 resolution or images sizes to work, your theme needs to support them. ### 󠀁[Crop images to fit](https://wordpress.org/documentation/article/gallery-block/?output_format=md#crop-images-to-fit)󠁿 You can select whether or not you’d like all of your images to be cropped in your Gallery block. 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. ### 󠀁[Randomize order](https://wordpress.org/documentation/article/gallery-block/?output_format=md#randomize-order)󠁿 You can choose to randomize the order of images in the Gallery block. Note: This setting will display the images in a randomized order on the published page/post. However, in the Block Editor, the images will appear in the order they were added. ### 󠀁[Aspect ratio](https://wordpress.org/documentation/article/gallery-block/?output_format=md#aspect-ratio)󠁿 The Aspect Ratio** **setting modifies the aspect ratio for all of the images within the Gallery with the choices in the dropdown list, enabling you to set a consistent aspect ratio. ### 󠀁[Advanced settings](https://wordpress.org/documentation/article/gallery-block/?output_format=md#advanced-settings)󠁿 [⌊The Advanced tab lets you add HTML anchor and CSS class(es) to your block.⌉⌊The Advanced tab lets you add HTML anchor and CSS class(es) to your block.⌉[ HTML anchor allows you to do [page jumping](https://wordpress.org/documentation/article/page-jumps/) 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. ## 󠀁[Block style settings](https://wordpress.org/documentation/article/gallery-block/?output_format=md#block-style-settings)󠁿 You can access the Style settings for the Gallery and Image block by clicking on the Styles tab. ![Styles tab of the gallery block](https://wordpress.org/documentation/files/2019/ 03/styles-Screenshot-2026-03-08-at-8.16.56-AM-404x1024.jpg) ### 󠀁[Color](https://wordpress.org/documentation/article/gallery-block/?output_format=md#color)󠁿 The Gallery block** **provides color settings options to change the background for the block For details, refer to this support article: [Color settings overview](https://wordpress.org/documentation/article/colors-settings-overview/) ### 󠀁[Dimensions](https://wordpress.org/documentation/article/gallery-block/?output_format=md#dimensions)󠁿 The Gallery block** **provides dimension settings options to add padding and margin. For details refer to this support article: [Dimension settings overview](https://wordpress.org/documentation/article/dimension-controls-overview/) ### 󠀁[Border](https://wordpress.org/documentation/article/gallery-block/?output_format=md#border)󠁿 The Gallery block provides border settings options to add border color, width, and radius. For details refer to this support article: [Border settings overview](https://wordpress.org/documentation/article/border-settings-overview/) ## 󠀁[Changelog](https://wordpress.org/documentation/article/gallery-block/?output_format=md#changelog)󠁿 * Updated 2026-03-08 (props to @awetz583 @CalolanC @Leonardus-Nugraha) - Removed duplicate content - Updated gallery link options - Updated block toolbar and settings screenshots - Updated settings with randomize feature * Updated 2026-02-15 - Updated toolbar & “transform to” screenshots(@rollybueno) * Updated 2025-07-05 - Added Enlarge on click option of the image * Updated 2024-01-16 - Updated screenshots and content for 6.3 - Fixed text formatting consistecy - Added missing alt text to screenshots * Updated 2023-03-29 - Added the option to clear duotone - Added information about the style settings tab - Added caption button for Gallery - Updated screenshot and Videos for 6.2 - Added Alt text * Updated 2022-12-12 - Added color settings * Updated 2022-11-20 - Adjusted images for mobile view - Added caption for images - Removed redundant content * 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? 󠀁[Cancel reply](https://wordpress.org/documentation/article/gallery-block/?output_format=md#respond)󠁿 [Log in to submit feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fwordpress.org%2Fdocumentation%2Farticle%2Fgallery-block%2F&locale=en_US). If you need support with something that wasn't covered by this article, please post your question in the [support forums](https://wordpress.org/support/forums/). First published March 7, 2019 Last updated March 17, 2026