useDocyrusDataGallery

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.

Edit on GitHubEditllms.txt

iOSAndroidExpo Go

Installation

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

Required Packages(5 packages)

pnpm add @docyrus/app-utils @docyrus/api-client @tanstack/react-query @tanstack/react-table @shopify/flash-list

A port of the web hook with the same options and result. It composes useDocyrusDataGrid (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 DataGallery.

Usage

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<Record<string, unknown>>({
    client,
    appSlug: 'base',
    dataSourceSlug: 'contact',
    displayConfig: { cardVariant: 'profile' },
    persistState: true,
    onCardClick: record => openContact(record.id as string)
  });

  return (
    <View className="flex-1">
      {toolbar}
      {sideFilters}
      <DataGallery {...galleryProps} />
    </View>
  );
}

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

useDocyrusDataGallery

On this page