Gallery Display

An image gallery block for WordPress with grid, masonry, mosaic, justified, and list layouts.

• Requires WordPress: 6.6 or later (tested up to 7.1)
• Requires PHP: 7.4 or later
• License: GPL-2.0-or-later

Layouts

Options

• 1 to 6 columns for grid, masonry, and mosaic.
• Thumbnail and full-size image sizes, listed from the sizes the site registers.
• Captions below the image or overlaid on it.
• Order by date, title, random, or manual arrangement. Mosaic adds a best-fit order that places wide images in the larger cells.
• Click behaviour: PhotoSwipe lightbox, attachment page, media file, or nothing.

Image metadata is read at render time, so editing an image in the media library updates every gallery it appears in.

Installation

Download a release zip and install it through Plugins → Add New → Upload Plugin, or clone the repository into wp-content/plugins/ and build it:

npm install
composer install
npm run build

Development

npm run start        # watch build
npm run build        # production build
npm run test:unit    # Jest
npm run lint         # ESLint, Stylelint and PHPCS
npm run format       # Prettier
composer run lint    # PHPCS on its own

CI runs on every pull request and every push to main (.github/workflows/ci.yml): PHPCS and a php -l syntax check across PHP 7.4 through 8.4, then ESLint, Stylelint, the Jest suite, and a production build. Both dependency trees are audited — composer audit and npm audit --omit=dev.

Blocks build from src/ into build/. src/render.php is copied into build/ by the WP_COPY_PHP_FILES_TO_DIST flag in the build scripts, so at runtime it lives at build/render.php.

Layout of the source

Extending

A companion plugin can register its own layout:

add_filter( 'gallery_display_valid_layouts', function ( $layouts ) {
    $layouts[] = 'carousel';
    return $layouts;
} );

wp.hooks.addFilter(
    'galleryDisplay.layouts',
    'my-plugin/carousel',
    ( layouts ) => [ ...layouts, { value: 'carousel', label: 'Carousel' } ]
);

// Load the layout's stylesheet in the editor preview.
wp.hooks.addFilter(
    'galleryDisplay.previewStylesheets',
    'my-plugin/carousel',
    ( sheets, layout ) =>
        layout === 'carousel'
            ? [ ...sheets, myPluginUrl + 'carousel.css' ]
            : sheets
);

Security notes

The editor preview renders into an `