How to add image galleries in WordPress?

The quickest way to add an image gallery in WordPress is with the built-in Gallery block: open a post or page, add a Gallery block, select or upload your images, and adjust the columns, cropping, and link settings in the sidebar. For more advanced layouts such as masonry grids, albums, filters, or slideshows, you can use a dedicated gallery plugin. Either way, you don't need to write any code to get a good-looking gallery.

Galleries are perfect for portfolios, product showcases, event photos, travel posts, and recipes with step-by-step images. This article covers how to create galleries with the block editor, how to add a lightbox, which gallery plugins are worth considering, how developers can build galleries in code, and how to keep galleries fast and accessible.

What Is a WordPress Image Gallery?

A WordPress image gallery is a collection of images displayed together in a structured layout, usually a grid, instead of one after another down the page. Galleries make it easier for visitors to browse many images at once and, with the right settings, click to see each image larger.

WordPress has supported galleries for a long time, originally through the [gallery] shortcode. Today, the Gallery block in the block editor is the main way to create them. Since WordPress 5.9, the Gallery block is made up of individual Image blocks nested inside it, which means each image in a gallery can have its own caption, link, and even styles.

Why Use Galleries on Your WordPress Site?

Galleries offer several benefits over simply stacking images:

• Better organization: Related images appear together in a tidy grid.
• Less scrolling: Visitors can see many images at a glance rather than scrolling through a long page.
• Visual storytelling: Portfolios, case studies, and event recaps become more engaging.
• Consistency: Uniform cropping and spacing give your content a polished look.
• Flexibility: You can link images to full-size versions, attachment pages, or custom URLs.

How to Create a Gallery With the Gallery Block

The Gallery block is available in every WordPress 6.x installation and works with both block themes and classic themes.

1. Open the editor: Go to Posts > Add New Post or edit an existing post or page.

2. Add the Gallery block: Click the + block inserter, search for "Gallery", and select it. You can also type /gallery on a new line.

3. Add images: Click Upload to add new images from your computer, or Media Library to choose existing images. In the Media Library, select multiple images, then click Create a new gallery.

4. Arrange your images: In the gallery editing screen, drag images to reorder them and add captions if you like. Click Insert gallery when you're done.

5. Reorder later if needed: Because each image is its own block, you can select an image inside the gallery and use the move arrows in the block toolbar to change its position.

6. Publish or update: Save your post and preview it on the front end.

Gallery Block Settings

With the Gallery block selected, the settings sidebar gives you several options:

• Columns: Choose how many images appear in each row. On smaller screens, WordPress automatically reduces the number of columns.
• Crop images to fit: When enabled, images are cropped so they align in a neat grid. Turn it off to show each image's full proportions.
• Link to: Choose whether clicking an image does nothing, opens the image file, opens the attachment page, or (in recent versions) expands the image in a lightbox.
• Resolution: Pick which image size the gallery uses, such as Medium, Large, or Full Size. Larger sizes look sharper but load more data.
• Randomize order: Available in recent versions, it shuffles images each time the page loads.

In the Styles tab, you can adjust block spacing (the gap between images), borders, and other design options supported by your theme.

Adding Captions

You can add a caption to the gallery as a whole by clicking below the grid and typing. To add captions to individual images, click an image inside the gallery and type in the caption area that appears beneath it. Keep captions short so they don't overwhelm the layout.

Editing Individual Images

Since each gallery image is an Image block, you can select one and:

• Add or edit its alt text in the sidebar.
• Set a custom link.
• Use the built-in crop, zoom, and aspect ratio tools from the toolbar.
• Replace it with a different image.

How to Add a Lightbox to Your Gallery

A lightbox opens an enlarged version of an image in an overlay without leaving the page. It's the most common way visitors expect galleries to behave.

Using the Built-In Expand on Click Option

Recent WordPress 6.x releases include a native lightbox for Image blocks called Expand on click:

1. Select your Gallery block.
2. In the settings sidebar, open the Link to option.
3. Choose Expand on click.

Now each image opens in a clean overlay when clicked. If you use a block theme, you can also enable the lightbox for all images across your site through the Site Editor under Appearance > Editor > Styles > Blocks > Image, depending on your WordPress version.

Using a Lightbox Plugin

If you want extra features, such as swiping between images, zoom, or social sharing, a lightbox plugin can help. Options include Simple Lightbox, FooBox (from the makers of FooGallery), and the lightboxes bundled with most gallery plugins.

How to Add a Gallery in the Classic Editor

If your site still uses the Classic Editor plugin, you can create galleries with the Add Media button:

1. Click Add Media above the editor.
2. Choose Create Gallery from the left-hand menu.
3. Select the images you want and click Create a new gallery.
4. Set the link, columns, random order, and size options.
5. Click Insert gallery.

WordPress inserts a [gallery] shortcode with the IDs of your images. You can also write it by hand:

[gallery ids="45,46,47,48" columns="4" size="medium" link="file"]

The shortcode still works in the block editor via a Shortcode block, but the Gallery block is the better choice for new content.

Using a Gallery Plugin for Advanced Layouts

The built-in Gallery block covers many needs, but a plugin makes sense when you want:

• Masonry or justified layouts.
• Albums that group multiple galleries.
• Filterable galleries with tags or categories.
• Slideshows and carousels.
• Video galleries.
• Watermarking, image protection, or proofing for clients.
• Galleries that can be managed and reused across multiple pages.

Well-known gallery plugins include:

Envira Gallery: A drag-and-drop gallery builder with responsive layouts, lightbox, albums, and add-ons for features like watermarking and social sharing in its paid tiers.

NextGEN Gallery: One of the longest-running gallery plugins, popular with photographers for its albums, slideshows, and e-commerce options for selling prints in the Pro version.

FooGallery: Offers several layout templates, including masonry and justified, plus a lightbox and filtering in its paid version.

Modula: Known for its custom grid that lets you resize individual images within the layout, along with filters, lightboxes, and video support.

Photo Gallery by 10Web: Provides a wide range of layouts, including mosaic, slideshow, and carousel views.

Creating a Gallery With a Plugin

The process is similar across most gallery plugins:

1. Install and activate the plugin from Plugins > Add New Plugin.
2. Create a new gallery from the plugin's menu in your dashboard.
3. Upload or select images from your Media Library.
4. Choose a layout and configure options like columns, spacing, lightbox, and hover effects.
5. Save the gallery.
6. Insert it into a post or page using the plugin's block or its shortcode.

A key advantage of plugin galleries is that you manage the gallery in one place. If you embed the same gallery on several pages, updating it once updates it everywhere.

Before choosing a plugin, check how it affects page speed. Some load large scripts and styles on every page. Look for options to load assets only where galleries appear.

How to Create a Reusable Gallery With Synced Patterns

If you want to reuse a native Gallery block across several pages, you can turn it into a synced pattern:

1. Select the Gallery block in the editor.
2. Click the three-dot menu in the block toolbar.
3. Choose Create pattern.
4. Give it a name and make sure Synced is turned on.
5. Save the pattern.

Now you can insert that pattern anywhere, and editing it updates every instance. You can manage your patterns under Appearance > Editor > Patterns in block themes, or from the pattern inserter in the editor.

Adding Galleries in Code

Developers sometimes need to output a gallery from a theme template or create a gallery automatically, for example, displaying all images attached to a custom post type.

Rendering a Gallery in a Template

The simplest way is to use gallery_shortcode() or do_shortcode() with a list of attachment IDs. This example outputs a gallery using image IDs stored in a custom field called project_gallery_ids (a comma-separated list). Place it in a template file in your child theme:

<?php
$sajjad_gallery_ids = get_post_meta( get_the_ID(), 'project_gallery_ids', true );

if ( ! empty( $sajjad_gallery_ids ) ) {
    $sajjad_ids = implode( ',', array_map( 'absint', explode( ',', $sajjad_gallery_ids ) ) );

    echo do_shortcode( '[gallery ids="' . esc_attr( $sajjad_ids ) . '" columns="3" size="medium_large" link="file"]' );
}

Building a Custom Gallery Grid

If you want full control over markup, you can loop through attachment IDs and use wp_get_attachment_image(), which automatically adds srcset, sizes, alt, width, height, and lazy loading:

<?php
/**
 * Output a simple gallery grid from an array of attachment IDs.
 *
 * @param int[]  $ids  Attachment IDs.
 * @param string $size Registered image size.
 */
function sajjad_render_gallery( array $ids, $size = 'medium_large' ) {
    if ( empty( $ids ) ) {
        return;
    }

    echo '<ul class="sajjad-gallery">';

    foreach ( $ids as $id ) {
        $id       = absint( $id );
        $full_url = wp_get_attachment_image_url( $id, 'full' );

        if ( ! $full_url ) {
            continue;
        }

        echo '<li class="sajjad-gallery__item">';
        echo '<a href="' . esc_url( $full_url ) . '">';
        echo wp_get_attachment_image( $id, $size );
        echo '</a>';
        echo '</li>';
    }

    echo '</ul>';
}

Then add a little CSS to your child theme's stylesheet, or under Appearance > Editor > Styles > Additional CSS in a block theme:

.sajjad-gallery {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
  gap: 1rem;
  list-style: none;
  margin: 0;
  padding: 0;
}

.sajjad-gallery__item img {
  display: block;
  width: 100%;
  height: 100%;
  aspect-ratio: 4 / 3;
  object-fit: cover;
  border-radius: 6px;
}

This produces a responsive grid that automatically adjusts the number of columns to the available width.

How to Keep Galleries Fast

Galleries can contain dozens of images, so performance matters.

1. Optimize images before or after upload: Compress images and consider serving WebP to reduce file sizes.
2. Choose a sensible resolution: In the Gallery block, use Medium or Large instead of Full Size for the grid. The lightbox can still show the larger version.
3. Rely on lazy loading: WordPress lazy loads gallery images automatically, so images further down the page only load when needed.
4. Split very large galleries: Instead of one gallery with 200 images, consider multiple smaller galleries, pagination (offered by many plugins), or an album structure.
5. Watch plugin assets: If you use a gallery plugin, check whether it loads its scripts on every page and disable that behavior if possible.
6. Use a CDN: Serving images from a CDN reduces latency for visitors around the world.

How to Make Galleries Accessible

Accessible galleries are better for everyone, including search engines.

• Add alt text to every image: Describe what's in the image. For purely decorative images, leave alt text empty.
• Use captions for context: Captions help all visitors understand what they're looking at.
• Check keyboard navigation: Make sure visitors can tab through images and open and close the lightbox using only the keyboard.
• Avoid auto-playing slideshows: If you use a slideshow, provide pause controls and avoid rapid transitions.
• Maintain contrast: If captions overlay images, ensure the text is readable against the background.

Troubleshooting Common Gallery Problems

Images appear in a single column: Your theme might not include styles for the Gallery block, or custom CSS is overriding it. Try switching to a default theme temporarily to check.

Images are cropped awkwardly: Turn off Crop images to fit in the Gallery block settings, or use the individual image crop tools to adjust focus.

Lightbox doesn't open: Confirm that Link to is set to Expand on click or Media File, and check for conflicts with another lightbox plugin or JavaScript errors in the browser console.

Gallery thumbnails look blurry: The gallery may be using a small image size scaled up. Choose a larger resolution, or regenerate thumbnails if you've changed image sizes.

Old [gallery] shortcodes look different after a theme change: The shortcode relies on theme styles. Converting it to a Gallery block (via the block's Convert to blocks option in the Classic block) usually gives more consistent results.

---

FAQ: Image Galleries in WordPress

---

Conclusion

Adding image galleries in WordPress is straightforward with the built-in Gallery block. You can upload images, arrange them, set columns and cropping, add captions, and enable a lightbox without leaving the editor. When you need albums, filters, or more elaborate layouts, a well-established gallery plugin fills the gap, and developers can always build fully custom galleries with wp_get_attachment_image() and a bit of CSS.

Whichever method you choose, keep performance and accessibility in mind: optimize your images, use sensible sizes, write meaningful alt text, and test your galleries on mobile. With those habits in place, your galleries will look great and load quickly for every visitor.