Data Gallery

Installation

pnpm dlx @docyrus/cli add @docyrus/ui-data-gallery

npx shadcn@latest add action-bar avatar badge button card checkbox input label popover select separator skeleton switch toggle-group

pnpm add @tanstack/react-table @tanstack/react-virtual react-querybuilder

Usage

import {
  DataGallery,
  DataGalleryToolbar,
  useDataGallery
} from '@docyrus/ui/components/data-gallery';
import type {
  ColumnDef
} from '@docyrus/ui/components/data-grid';
import type {
  DataGalleryCardConfigSerializable
} from '@docyrus/ui/components/data-gallery';

const columns: ColumnDef<Product>[] = [
  { accessorKey: 'name', meta: { label: 'Name', cell: { variant: 'short-text' } } },
  { accessorKey: 'cover', meta: { label: 'Cover', cell: { variant: 'image' } } },
  { accessorKey: 'status', meta: {
    label: 'Status',
    cell: { variant: 'status', options: statusOptions }
  } }
  // ...
];

function MyGallery() {
  const [cardConfig, setCardConfig] = useState<DataGalleryCardConfigSerializable>({
    titleField: 'name',
    descriptionField: 'tagline',
    coverImageField: 'cover',
    badgeField: 'status'
  });

  const galleryProps = useDataGallery({
    data,
    columns,
    enableSearch: true,
    enableGrouping: true,
    displayConfig: {
      cardVariant: 'detailed',
      coverStyle: 'top-md',
      columnCount: 'flex'
    }
  });

  const {
    table, displayConfig, setDisplayConfig, searchQuery, setSearchQuery
  } = galleryProps;

  return (
    <div className="flex flex-col gap-3">
      <DataGalleryToolbar
        table={table}
        displayConfig={displayConfig}
        onDisplayConfigChange={setDisplayConfig}
        cardConfig={cardConfig}
        onCardConfigChange={setCardConfig}
        searchQuery={searchQuery}
        onSearchQueryChange={setSearchQuery}
        enableFilter
        enableSort
        enableGroup
        enableDisplay
        enableCardConfig />

      <DataGallery
        {...galleryProps}
        cardConfig={cardConfig}
        height={600} />
    </div>
  );
}

Card Variants

The card variant controls the default layout. Each variant ships with sensible defaults that the display menu can still override. Pick the variant via displayConfig.cardVariant or per-card via cardConfig.variant. The demo above exposes the variant picker in its Display toolbar menu — try switching between them live.

Card Slots

Each card composes from a fixed set of slots. Bind a column ID to a slot via cardConfig, or supply a custom renderer (renderAvatar, renderCover, renderBadge, renderTimeline, renderActions). For complete control, return your own JSX from renderCard.

bodyFields defaults to every visible column the table exposes minus the ones already bound to a dedicated slot.

Cover & avatar value resolution

coverImageField and avatarField read from row.original[slug] directly rather than through TanStack's accessorFn. Docyrus columns run a normalizeFieldValue step inside the accessor that flattens field-image arrays ([{ signed_url, … }]) to a JSON string and field-userSelect objects ({ id, name, avatar_url }) to a UUID — both lose the URL the card needs. The raw read keeps the original shape so:

• Cover images resolve through resolveImageUrl, which walks array → object → first usable URL key (signed_url, signedUrl, url, src, image_url, thumb_url).
• Avatars resolve through resolveAvatarUrlAndLabel. When the bound column has cellOpts.variant === 'user', the helper looks the row's user id up in cellOpts.options (the tenant-wide users list useDocyrusDataGrid injects), picking the avatar URL + display name from the option entry — so users still get their real photos even when the expanded row payload only carries { id, name }.

Avatar / cover duplicate guard

When avatarField and coverImageField are bound to the same column (typically from an old auto-detect or saved view that picked company_logo for both), the avatar slot is suppressed automatically. The cover already carries the image; rendering a thumbnail of it next to the checkbox just doubles the visual.

Layout lockstep

coverStyle: 'left' and layoutOrientation: 'horizontal' are coupled — picking one auto-promotes the other via resolveCardLayout. Setting coverStyle: 'top-md' together with layoutOrientation: 'horizontal' falls back to 'vertical' so the cover doesn't stretch awkwardly alongside the body.

Display Config

The displayConfig object is owned by useDataGallery and mutated by the toolbar's display menu. Pass displayConfig as the initial state; the hook re-syncs only when you swap the prop identity (e.g. switching saved views).

Variant changes are preset applications

Picking a new cardVariant from the display menu batch-updates every display field defined in VARIANT_DISPLAY_PRESETS (cover style, density, label visibility, footer toggle, …) rather than just renaming the variant. After application the display config stays the single source of truth — cardVariant is a "last preset applied" label rather than a runtime override. The variant additionally drives non-display visual details (avatar / title sizing) via VARIANT_VISUAL_DEFAULTS at render time.

Dynamic card height

Cards size themselves to their content; the virtualizer reads each row's real height after mount via measureElement and updates row positions in place. estimatedCardHeight is just the initial guess used for the first paint — undershoot is fine, the measured value replaces it once the row renders. This keeps tall content (extra body fields, wrapped descriptions, large covers) from getting clipped inside a fixed-height row band.

Color treatment

Every option-backed chip — status, select, enum, multi-select, tag-select, relation — renders with the same neutral surface: shared border, transparent background, plain foreground text. The option's color appears only as a small dot before the label, run through humanizeColor() (a color-mix in OKLab that pulls Tailwind-500 defaults toward an earthy warm-neutral so cards don't pick up a "designer palette" of saturated greens / purples / cyans). It's the Linear / Notion / Tana pattern — the hue identity survives, but it doesn't dominate.

Toolbar

The toolbar is a thin orchestrator over the standalone menu components. Enable each section via a feature flag.

The <DataGalleryToolbar> also supports startContent and endContent slots for custom controls, plus an onAdd handler that renders a primary Add button on the right edge.

Selection & Actions

Set enableRowSelection on useDataGallery (TanStack default applies). Each card shows a hover-revealed checkbox; multi-selection raises an ActionBar. Pass actions via the actions prop on <DataGallery>:

<DataGallery
  {...galleryProps}
  actions={[
    { key: 'archive', label: 'Archive', onAction: rows => archive(rows) },
    { key: 'delete', label: 'Delete', variant: 'destructive', onAction: rows => deleteAll(rows) }
  ]} />

Pagination

Set pagingMode: 'standard' to enable a paginated footer instead of virtual scrolling:

const galleryProps = useDataGallery({
  data,
  columns,
  pagingMode: 'standard',
  pageSize: 24
});

API Reference

useDataGallery(options)

<DataGallery />

Accepts the spread return of useDataGallery plus:

<DataGalleryToolbar />

Type Exports

Components

Helper Exports

Re-exported from @docyrus/ui/components/data-gallery:

Re-exported from @docyrus/ui/components/data-gallery/lib/data-gallery: