> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frogbot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Collection gallery

> Show a collection as a grid of cards with images.

Add a gallery entry to `admin.views` to show documents as a grid of cards: an image, the title and a few fields on each. Gallery cards look like [board](https://docs.frogbot.ai/admin/collection-board.md) cards and use the same keys, but they sit in a grid and can't be dragged.

See the complete [Collection views reference](https://docs.frogbot.ai/configuration/collections.md#collection-views).

```ts theme={"theme":"tokyo-night"}
export const Companies: CollectionConfig = {
  slug: 'companies',
  admin: {
    useAsThumbnail: 'logo',
    views: [
      { type: 'list' },
      {
        type: 'gallery',
        label: 'Logos',
        thumbnailFit: 'contain',
        defaultFields: ['industry', 'owner'],
      },
      { type: 'board', label: 'Lifecycle', groupBy: 'lifecycle', useAsThumbnail: false },
    ],
  },
  fields: [
    { name: 'name', type: 'text' },
    { name: 'logo', type: 'upload', relationTo: 'media' },
    { name: 'industry', type: 'select', options: ['software', 'finance'] },
    { name: 'owner', type: 'relationship', relationTo: 'users' },
    { name: 'lifecycle', type: 'select', options: ['lead', 'customer'] },
  ],
}
```

An upload collection needs nothing set: each card shows the document's own file.

```ts theme={"theme":"tokyo-night"}
export const Media: CollectionConfig = {
  slug: 'media',
  file: true,
  admin: { views: [{ type: 'list' }, { type: 'gallery', label: 'Grid' }] },
  fields: [{ name: 'alt', type: 'text' }],
}
```

## Gallery properties

| Property | Type | Required / default | Behavior |
| - | - | - | - |
| `type` | `'gallery'` | Yes | Selects the gallery layout. |
| `slug` | `string` | No; defaults to `'gallery'` | Unique normalized route and preference key. The first view uses the collection's root route. |
| `label` | `string` | No; defaults to `'Gallery'` | Label on the view's tab. |
| `icon` | `AdminIcon` | No; `'tile'` | Icon on the view's tab. |
| `useAsThumbnail` | `string \| false` | No; the collection's `useAsThumbnail` | Upload field shown as each card's image, or `false` for none. See [Card images](#card-images). |
| `thumbnailFit` | `'cover' \| 'contain'` | No; `'cover'` | `'cover'` fills the image area and crops, for photos. `'contain'` fits the whole image, for logos. |
| `defaultFields` | `string[]` | No | Dot paths to the fields shown under each card's title, in display order. |
| `filter` | `Where` | No | Invisible base filter applied to the gallery, as plain data. |
| `defaultSort` | `Sort` (`string \| string[]`) | No | Initial card order. Prefix a field with `-` for descending order. |
| `searchableFields` | `string[]` | No | Not read by the gallery. Its search uses the list view's `searchableFields`, plus `useAsTitle`. |
| `pagination` | `ViewPagination` | No; `defaultLimit: 25` | `defaultLimit` sets the cards per page, and `limits` the page-size choices. |
| `access` | `({ req }) => boolean \| Promise<boolean>` | No; collection access | Controls whether the current user can open the gallery without replacing collection operation access. |
| `components` | `ViewComponents & GalleryComponents` | No | Configures shared view slots and gallery components. |

## Gallery components

| Property | Type | Required / default | Behavior |
| - | - | - | - |
| `actions` | `FrogBotComponent[]` | No; `[]` | Renders in the page header, top right. |
| `toolbar` | `FrogBotComponent[]` | No; `[]` | Renders in the gallery's view controls, before Filters. Below the small breakpoint it moves into a right-aligned row under the toolbar. |
| `menuItems` | `FrogBotComponent[]` | No; `[]` | Adds entries to the gallery menu. |
| `beforeView` | `FrogBotComponent[]` | No; `[]` | Renders inside the view frame before the header. |
| `afterView` | `FrogBotComponent[]` | No; `[]` | Renders inside the view frame after the gallery, above its page controls. |
| `beforeCards` | `FrogBotComponent[]` | No; `[]` | Renders before the grid. |
| `afterCards` | `FrogBotComponent[]` | No; `[]` | Renders after the grid. |
| `Card` | `FrogBotComponent` | No; built-in card body | Replaces each card's body and receives the document as its `row` prop. The card around it still opens the record panel. |
| `NoResults` | `FrogBotComponent` | No; built-in empty state | Replaces the grid when the gallery matches no records. |

```tsx theme={"theme":"tokyo-night"}
'use client'

export function CompanyCard({ row }: { row: { name?: string; website?: string } }) {
  return (
    <>
      <strong>{row.name}</strong>
      <span>{row.website}</span>
    </>
  )
}
```

```ts theme={"theme":"tokyo-night"}
{
  type: 'gallery',
  components: { Card: '/components/CompanyCard#CompanyCard' },
}
```

## Card images

Cards show the collection's [`admin.useAsThumbnail`](https://docs.frogbot.ai/configuration/collections#card-images), which defaults to the collection's first upload field. On an upload collection with no upload field, each card shows the document's own file. A gallery can set its own `useAsThumbnail`: another top-level upload field, or `false` for no images. A bad field name stops startup with an error naming the collection, the view and the field.

The image area has a fixed height, so cards line up. A card with no image, such as a company with no logo, keeps the image area and shows a document icon.

## Layout and paging

Cards fill as many columns as fit the page, at least 240px wide, or 150px on a phone. The gallery loads one page at a time, 25 cards unless `pagination.defaultLimit` says otherwise, with page controls below the grid.

Clicking a card opens the record in the [record panel](https://docs.frogbot.ai/admin/record-panel.md) beside the gallery. Saving or deleting there refreshes the page. With the collection's [`admin.useAsDone`](https://docs.frogbot.ai/configuration/collections#done-records) set, each built-in card starts with a check circle that toggles the record's done field, and done cards show a muted title. The card open in the panel shows the shared selected style.

The gallery's sort, filters, card fields and page size are saved per user. **Reset to default** in the view menu returns to the config.

## Styling

Gallery styles sit in FrogBot's CSS layer, so an app's own CSS overrides them without extra specificity. The grid is `.collection-gallery`, each card `.collection-gallery__card`, and the card body uses the board's classes: `.fb-card__image`, `.fb-card__title` and `.fb-card__field`. The `--fb-card-image-height` variable sets the image area's height.


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