# useDocyrusDataGallery
URL: /docs/web/hooks/use-docyrus-data-gallery

One-call wiring of a Docyrus data source to a fully configured DataGallery + toolbar (DataGridViewSelect, search, filters, sort, group, gallery display menu, card config menu) — including row fetching, saved views, pivot filters, and automatic card field detection.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-gallery
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)
- [@tanstack/react-table](https://tanstack.com/table/latest)
- [@tanstack/react-virtual](https://tanstack.com/virtual/latest)
- [react-querybuilder](https://react-querybuilder.js.org)

This hook is distributed as source. It requires an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree.

## Overview

`useDocyrusDataGallery` composes [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) and layers a gallery-specific presentation on top. The result is a ready-to-render setup with:

- **Backend wiring** — data source schema fetch, items query, saved views, side filters, pivot filters (all from the data-grid hook).
- **Tenant-aware formatting** — inherited from the composed grid hook. Date / datetime / number cells pick up the formatters installed by [`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `collection` | `DocyrusDataGridCollection<TData>` | — | TanStack DB collection. The hook calls `collection.list(listParams)` to fetch rows. |
| `data` | `Array<TData>` | — | Pre-resolved rows. Skips the internal items query. |
| `appSlug` | `string` | — | Required for data source schema and view fetches. |
| `dataSourceSlug` | `string` | — | Required for data source schema and view fetches. |
| `listParams` | `DocyrusDataGridListParams` | — | Extra query params merged on top of view-derived ones. |
| `pivotFilters` | `ReadonlyArray<DocyrusPivotFilterGroupField>` | — | Render pivot strips above the toolbar. |
| `enableSideFilters` | `boolean` | `false` | Enable the side-panel filter rail. |
| `sideFiltersConfig` | `DocyrusDataGridSideFiltersConfig<TData>` | — | Side panel config. |
| `cardConfig` | `DataGalleryCardConfigSerializable` | auto-detected | Initial card field bindings. |
| `onCardConfigChange` | `(config) => void` | — | Fires whenever the card config changes. |
| `displayConfig` | `Partial<DataGalleryDisplayConfig>` | — | Initial display config. |
| `onDisplayConfigChange` | `(config) => void` | — | Fires whenever the display config changes. |
| `enableSearchInput` | `boolean` | `true` | Toggle the toolbar search input. |
| `enableFilterMenu` | `boolean` | `true` | Toggle the filter menu. |
| `enableSortMenu` | `boolean` | `true` | Toggle the sort menu. |
| `enableGroupMenu` | `boolean` | `true` | Toggle the group menu. |
| `enableDisplayMenu` | `boolean` | `true` | Toggle the gallery display menu. |
| `enableCardConfigMenu` | `boolean` | `true` | Toggle the card config menu. |
| `enableViewSelect` | `boolean` | `true` | Toggle the view picker. |
| `enableReloadButton` | `boolean` | `true` | Toggle the reload button. |
| `viewSelectVariant` | `'horizontal-tabs' \| 'dropdown' \| 'vertical-tabs'` | `'horizontal-tabs'` | View picker variant. |
| `onAdd` | `() => void` | — | When supplied, renders a primary "Add" button on the toolbar's right edge. |
| `addLabel` | `string` | `'Add'` | Label for the add button. |
| `minCardWidth` | `number` | `260` | Min card width for the `'flex'` column count auto-fit. |
| `estimatedCardHeight` | `number` | `360` | Initial virtualizer estimate — `measureElement` replaces per-row after first paint. |
| `excludeFieldSlugs` | `ReadonlyArray<string>` | — | Drop stale field slugs from the data source schema before downstream consumers see it. See the Stale Schema Escape Hatch section. |
| `overscan` | `number` | `3` | Virtualizer overscan rows. |
| `users` | `ReadonlyArray<CellUserOption>` | — | Tenant users for `field-userSelect` cells. Forwarded to the grid. |
| `formatDate`, `formatDateTime`, `formatNumber` | functions | — | Tenant-aware formatters. Forwarded to the grid. |
| `bulkActions` | `false \| ReadonlyArray<DocyrusDataGridBulkAction>` | `['update', 'delete', 'export']` | Action bar bulk actions. |
| `extraBulkActions` | `Array<DataGalleryAction<TData>>` | — | Extra row-selection actions. |

### Returns

| Key | Type | Description |
|-----|------|-------------|
| `galleryProps` | `DocyrusDataGalleryProps<TData>` | Spread onto `<DataGallery>`. Includes `table`, `displayConfig`, `virtualizer`, `containerRef`, etc. |
| `toolbar` | `ReactNode` | Pre-wired gallery toolbar element. Render above `<DataGallery>`. |
| `cardConfig` | `DataGalleryCardConfigSerializable` | Current card field bindings. |
| `setCardConfig` | `(updater) => void` | Card config setter. |
| `displayConfig` | `DataGalleryDisplayConfig` | Current display config. |
| `setDisplayConfig` | `(updater) => void` | Display config setter. |
| `searchInput` | `string` | Immediate search input value. |
| `searchKeyword` | `string` | Debounced search keyword sent to the backend. |
| `setSearchInput` | `(value) => void` | Search input setter. |
| `items` | `Array<TData>` | Resolved rows. |
| `fields` | `Array<FullField>` | Data source fields (filter-friendly shape). |
| `dataSource` | `DataSource \| undefined` | Resolved data source metadata. |
| `activeViewId` | `string` | Current saved view id. |
| `setActiveViewId` | `(viewId) => void` | View setter. |
| `views` | `Array<SavedDataGridView>` | Available saved views. |
| `pivotFilterRule` | `Array<PivotFilterRule> \| null` | Combined pivot filter rule. |
| `sideFilters` | `ReactNode` | Side panel element (or `null`). |
| `sideFiltersExpanded`, `setSideFiltersExpanded`, `sideFiltersQuery` | — | Side filter wiring. |
| `resolvedListParams` | `DocyrusDataGridListParams` | The list params actually sent to the backend. |
| `pagingMode` | `'standard' \| 'virtual-scroll' \| undefined` | Resolved paging mode for the active view. |
| `reload` | `() => void` | Refetch metadata + items. |
| `refetch` | `() => void` | Alias of `reload`. |
| `isLoading` | `boolean` | Initial load indicator. |
| `error` | `Error \| null` | Schema or items error. |
| `gridViewSelectProps` | `Pick<DataGridViewSelectProps, ManagedProps>` | View-select props with the hook's `onViewSave` / `onViewCreate` wrappers already attached — saving a view from a custom toolbar still persists gallery state. |
| `pivotFiltersStrip` | `ReactNode` | The pivot strip element (or `null` when no `pivotFilters` configured) — render before the toolbar when composing a custom layout. |

## Helper Exports

### `detectCardConfigFromFields(fields)`

Build a `DataGalleryCardConfigSerializable` from a `DataSourceField[]`. Used internally; exported so consumers can re-run the detection after schema changes or build their own card configs.

```tsx
import { detectCardConfigFromFields } from '@/hooks/use-docyrus-data-gallery';

const cardConfig = detectCardConfigFromFields(dataSource.fields);
```

## Related

- [`DataGallery`](/docs/web/components/data-gallery) — the standalone presentation component.
- [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) — table-mode sibling; gallery composes it internally.
- [`useDocyrusDataViewSelect`](/docs/web/hooks/use-docyrus-data-view-select) — shared saved view storage.