payload-media-gallery

A Payload CMS 3.x plugin that replaces the default table view of an upload collection with a visual grid gallery.

Features

• Responsive grid of thumbnails for any upload collection
• Lightbox modal with keyboard navigation (←/→, Esc) and per-page paging
• Drag-and-drop bulk upload (anywhere on the gallery surface)
• Metadata sidebar with filename, format, size, dimensions, dates
• Collapsible "Preview sizes" accordion listing every generated image size
• Inline delete with confirmation
• Bulk select via per-card checkboxes (uses Payload's built-in selection state)
• Field picker drawer support — works as a relationship picker in other collections
• Themed via Payload's --theme-elevation-* CSS variables, plus an optional --media-gallery-accent override

Requirements

• Payload ^3.0.0
• React ^19.0.0, React DOM ^19.0.0
• Next.js ^15 or ^16
• An upload-enabled collection

Installation

pnpm add payload-media-gallery
# or
npm install payload-media-gallery
# or
yarn add payload-media-gallery

Usage

Add the plugin to your payload.config.ts and pass the slug of the upload collection you want to attach the gallery to:

import { buildConfig } from 'payload'
import { mediaGalleryPlugin } from 'payload-media-gallery'

export default buildConfig({
  collections: [
    {
      slug: 'media',
      upload: true,
      fields: [
        { name: 'alt', type: 'text' },
      ],
    },
    // ... your other collections
  ],
  plugins: [
    mediaGalleryPlugin({
      collectionSlug: 'media',
    }),
  ],
})

After installing, regenerate the Payload import map:

pnpm payload generate:importmap

This also runs automatically on next dev and next build.

Options

| Option | Type | Required | Description | | --- | --- | --- | --- | | collectionSlug | string | yes | The slug of the upload collection the gallery should replace the default list for. |

Theming

The gallery inherits Payload's neutral theme colors by default. To customize the accent color (selection highlight, checkbox, hover borders, link color), set a CSS custom property anywhere in your admin styles:

:root {
  --media-gallery-accent: #b1852f;
}

How it works

The plugin attaches a beforeListTable admin component to the configured collection and registers a small REST endpoint at /api/media-gallery/delete for the lightbox delete action. It does not modify your collection's schema, hooks, or access control.

Local development

This repo includes a dev/ sandbox — a minimal Payload + Next.js app that imports the plugin via workspace path so you can iterate with HMR and an in-memory MongoDB.

pnpm install
cp dev/.env.example dev/.env
# edit dev/.env and set PAYLOAD_SECRET to anything

pnpm dev

Open http://localhost:3000/admin. The seeded login is [email protected] / test.

The sandbox uses mongodb-memory-server by default — no Mongo install needed. To use a real Mongo instance, set DATABASE_URL in dev/.env.

Building for publish

pnpm build

This runs copyfiles (assets like SCSS), tsc (type declarations), and swc (JS) to produce the dist/ folder consumed by the publishConfig exports.

License

MIT — see LICENSE.