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

Docyrus-backed card gallery for React Native — composes useDocyrusDataGrid for schema, saved views, server filters / sort / search / paging and pivot / side filters, and adds gallery-owned card + display config, a toolbar and props for the native DataGallery.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-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)
- [@shopify/flash-list](https://shopify.github.io/flash-list/)

A port of the web hook with the same options and result. It composes [`useDocyrusDataGrid`](/docs/native/hooks/use-docyrus-data-grid) (read-only, grid toolbar switched off) for the data layer and adds what a gallery owns: the card field bindings (auto-detected from the schema, or the saved view's `galleryCardConfig`), the display config (variant, columns, density, cover …), a debounced search that becomes the server `filterKeyword`, and a toolbar. Spread `galleryProps` onto the native [rn-data-gallery](/docs/native/docyrus/data-gallery).

## Usage

```tsx
import { View } from 'react-native';

import { useDocyrusClient } from '@docyrus/signin/react-native';

import { DataGallery } from '@/components/docyrus-native/data-gallery';
import { useDocyrusDataGallery } from '@/hooks/docyrus-native/use-docyrus-data-gallery';

export function ContactGallery() {
  const client = useDocyrusClient();
  const { toolbar, galleryProps, sideFilters } = useDocyrusDataGallery
  );
}
```

Saving or creating a view from the toolbar's view picker injects the current `galleryCardConfig` / `galleryDisplayConfig` into the payload, so the gallery layout travels with the view (and is shared with the grid's gallery display mode).

## API Reference

### Options (`UseDocyrusDataGalleryOptions<TData>`)

Every [`useDocyrusDataGrid`](/docs/native/hooks/use-docyrus-data-grid#options-usedocyrusdatagridoptionstdata) option is accepted and forwarded (`client`, `appSlug`, `dataSourceSlug`, `listParams`, `pivotFilters`, `enableSideFilters` / `sideFiltersConfig`, `persistState`, `onCardClick`, `users`, `formatDate`, …) **except** the grid-only `enableSearch`, `enableRowHeightMenu`, `enableRowMarkers`, `trackChanges`, `onSaveChanges`, `onRowAdd`, `readOnly` (always read-only) and the grid's `cardConfig`. Gallery options:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `cardConfig` | `DataGalleryCardConfigSerializable` | auto-detected | Initial card bindings (saved view → this → `detectCardConfigFromFields`). |
| `onCardConfigChange` | `(config) => void` | — | Fires on every card-config change. |
| `displayConfig` | `Partial<DataGalleryDisplayConfig>` | defaults | Initial display config (merged with the view's `galleryDisplayConfig`). |
| `onDisplayConfigChange` | `(config: DataGalleryDisplayConfig) => void` | — | Fires on every display change. |
| `showSelectColumn` | `boolean` | `true` | Keep row selection (long-press a card). |
| `enableSearchInput` | `boolean` | `true` | Search input (debounced 250 ms → `filterKeyword`). |
| `enableFilterMenu` | `boolean` | `true` | Filter chip. |
| `enableSortMenu` | `boolean` | `true` | Sort chip. |
| `enableGroupMenu` | `boolean` | `true` | Group chip. |
| `enableDisplayMenu` | `boolean` | `true` | Display sheet. |
| `enableCardConfigMenu` | `boolean` | `true` | Card fields sheet. |
| `enableViewSelect` | `boolean` | `true` | Saved-view picker. |
| `enableReloadButton` | `boolean` | `true` | Reload button. |
| `viewSelectVariant` | `'horizontal-tabs' \| 'dropdown' \| 'vertical-tabs'` | `'horizontal-tabs'` | View picker variant. |
| `onAdd` / `addLabel` | `() => void` / `string` | — / `'Add'` | Toolbar add button. |
| `minCardWidth` | `number` | `260` | Card width floor for the column clamp. |
| `estimatedCardHeight` / `overscan` | `number` | — | Accepted for parity; ignored. |

### Result (`UseDocyrusDataGalleryResult<TData>`)

Everything `useDocyrusDataGrid` returns except `gridProps`, `toolbar` and `sidePanel` (`table`, `items`, `fields`, `views`, `forms`, `activeViewId`, `setActiveViewId`, `activeViewForm`, `formViewProps`, `resolvedListParams`, `pagingMode`, `pivotFilterRule`, `pivotFiltersStrip`, `sideFilters`, `sideFiltersExpanded`, `setSideFiltersExpanded`, `sideFiltersQuery`, `selectedRows`, `selectedRowCount`, `reload`, `refetch`, `isLoading`, `error`, `hasNoViews`, `dataSource`, `gridViewSelectProps` — wrapped to inject the gallery config on save), plus:

| Field | Type | Description |
|-------|------|-------------|
| `galleryProps` | `DocyrusDataGalleryProps<TData>` | Spread onto `<DataGallery>` (below). |
| `toolbar` | `ReactNode` | Pivot strips → view picker → search → scrollable chips (filter, sort, group, display, card fields, reload, add). |
| `cardConfig` / `setCardConfig` | `DataGalleryCardConfigSerializable` / setter (value or updater) | Card bindings. |
| `displayConfig` / `setDisplayConfig` | `DataGalleryDisplayConfig` / setter | Display config. |
| `searchInput` / `setSearchInput` | `string` / `(value) => void` | Immediate search value. |
| `searchKeyword` | `string` | Debounced keyword sent as `filterKeyword`. |

`DocyrusDataGalleryProps<TData>`:

| Field | Type | Description |
|-------|------|-------------|
| `table` / `tableMeta` | TanStack | Grid table + meta. |
| `displayConfig` | `DataGalleryDisplayConfig` | Current display config. |
| `onClearFilters` / `hasActiveFilters` | `() => void` / `boolean` | Empty-state reset (toolbar chips + search; side filters count as active). |
| `selectedRowCount` / `getSelectedRows` | `number` / `() => TData[]` | Selection. |
| `columnsPerRow` | `number` | Measured column count. |
| `onContainerLayout` | `(event) => void` | **Native.** Width measurement (web: `containerRef`). |
| `minCardWidth` | `number` | **Native.** Column clamp. |
| `pagingMode` | `'standard' \| 'virtual-scroll'` | Resolved paging mode. |
| `isReloading` | `boolean` | Background refetch. |
| `onRefresh` | `() => void` | **Native.** Pull-to-refresh → `reload`. |

## Native deltas

- `galleryProps` drops web `containerRef` / `virtualizer` (FlashList + `onLayout`) and adds `onContainerLayout`, `minCardWidth`, `onRefresh`.
- `estimatedCardHeight` / `overscan` are accepted and ignored.
- The toolbar uses the grids' stacked native layout (chips open bottom sheets).
- `persistState` stores the gallery layer (search, card, display config) under the `…:gallery` key in `lib/storage`, next to the grid's own entry.

## Exports

| Export | Description |
|--------|-------------|
| `useDocyrusDataGallery` | The hook. |
| `detectCardConfigFromFields(fields)` | Re-exported card-slot auto-detection. |

## Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusDataGalleryOptions<TData>` / `UseDocyrusDataGalleryResult<TData>` | Options / result. |
| `DocyrusDataGalleryProps<TData>` | `galleryProps` shape. |