Thumbnails

thumbnail populates a hidden thumbnailURL field on your upload documents, which the admin panel uses to show a preview image in list and edit views, and which is available in every API response.

payload.config.ts

bunnyStorage({
  collections: { media: true },
  storage: {/* ... */},
  thumbnail: true, // enable with defaults
})

Images — uses the original file, or a specific size if sizeName is set.
Bunny Stream videos — uses the frame captured at stream.thumbnailTime.

Options

Option	Type	Default	Description
`sizeName`	`string`	–	Use a named image size from your collection’s `imageSizes` instead of the original file. Falls back to the original if the size is missing on a given document.
`streamAnimated`	`boolean`	`false`	For Stream videos, use an animated WebP preview (`preview.webp`) instead of a static JPEG (`thumbnail.jpg`).
`urlTransform`	`boolean \| object \| function`	`{ appendTimestamp: true }`	Same forms as `urlTransform`, applied to the thumbnail URL. `false` turns the transform off.
`urlTransform.appendTimestamp`	`boolean`	`true`	Append a `t=<timestamp>` query parameter so browsers fetch the latest thumbnail after a file changes.
`urlTransform.queryParams`	`Record<string, string>`	`{}`	Static query parameters appended to the thumbnail URL — handy for Bunny’s Image Optimizer.

Cache-busting with appendTimestamp

Thumbnails have urlTransform.appendTimestamp on by default. When a file is replaced (for example, during image cropping), the timestamp changes and browsers fetch the new version instead of a cached copy. While it is enabled, the plugin also disables Payload’s cache tags for the thumbnail field, to avoid caching conflicts. Opt out in the options if you don’t want it:

thumbnail: {
  urlTransform: { appendTimestamp: false },
}

To make this effective on Bunny’s side too, go to your Pull Zone → Caching → enable Vary Cache for URL Query String, and add t to the vary parameter list.If you need immediate cache invalidation everywhere instead of relying on the browser refetching, use cache purging.

Resizing with queryParams

thumbnail: {
  urlTransform: {
    queryParams: {
      width: '300',
      height: '300',
      quality: '85',
    },
  },
}

Using a named image size

thumbnail: {
  sizeName: 'thumbnail', // matches a size defined in upload.imageSizes
}

Custom transform function

For full control over the thumbnail URL, pass a function as thumbnail.urlTransform. It replaces appendTimestamp and queryParams, and you build the URL yourself. sizeName and streamAnimated still apply.

thumbnail: {
  sizeName: 'thumbnail',
  urlTransform: ({ baseUrl }) => `${baseUrl}?class=thumb`,
}

The function receives the same arguments as the urlTransform function (baseUrl, collection, filename, prefix, data) and returns the final URL string.

Collection overrides

collections: {
  gallery: {
    thumbnail: {
      sizeName: 'thumbnail',
    },
  },
  documents: {
    thumbnail: false, // no thumbnails for this collection
  },
}

A collection thumbnail keeps the global thumbnail.urlTransform unless it sets its own. A collection thumbnail.urlTransform object merges onto a global object and replaces a global function. See Collection overrides for the full list of options you can tune per collection.

Documentation

Configuration

CLI

Guides

Options

Cache-busting with appendTimestamp

Resizing with queryParams

Using a named image size

Custom transform function

Collection overrides

​Options

​Cache-busting with appendTimestamp

​Resizing with queryParams

​Using a named image size

​Custom transform function

​Collection overrides

Options

Cache-busting with appendTimestamp

Resizing with queryParams

Using a named image size

Custom transform function

Collection overrides