> ## Documentation Index
> Fetch the complete documentation index at: https://payload-storage-bunny.seshuk.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Thumbnails

> Populate a thumbnailURL field on upload documents for admin previews and API responses.

`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.

```ts payload.config.ts theme={null}
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`](/v4/configuration/stream/overview#options).

## 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`](/v4/configuration/url-transforms), 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](https://docs.bunny.net/docs/stream-image-optimization?ref=fndfoymy0j). |

## 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:

```ts theme={null}
thumbnail: {
  urlTransform: { appendTimestamp: false },
}
```

<Tip>
  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](/v4/configuration/cache-purge).
</Tip>

## Resizing with queryParams

```ts theme={null}
thumbnail: {
  urlTransform: {
    queryParams: {
      width: '300',
      height: '300',
      quality: '85',
    },
  },
}
```

## Using a named image size

```ts theme={null}
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.

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

The function receives the same arguments as the [`urlTransform` function](/v4/configuration/url-transforms#custom-transform-function) (`baseUrl`, `collection`, `filename`, `prefix`, `data`) and returns the final URL string.

## Collection overrides

```ts theme={null}
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](/v4/configuration/collection-overrides) for the full list of options you can tune per collection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.