DataGallery

Installation

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

pnpm add @tanstack/react-table @shopify/flash-list tailwind-variants

DataGallery renders the rows of a TanStack table as cards. useDataGallery owns the table, the display config and the search state; spread its result onto <DataGallery> and <DataGalleryToolbar>. The same card engine (DataGalleryCard) powers the data grid's gallery display mode and useDocyrusDataGallery for Docyrus data sources.

Usage

import { useState } from 'react';
import { View } from 'react-native';

import { type ColumnDef } from '@tanstack/react-table';

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

type Product = { id: string; name: string; category: string; price: number; image: string };

const columns: Array<ColumnDef<Product>> = [
  { id: 'name', accessorKey: 'name', header: 'Name' },
  { id: 'category', accessorKey: 'category', header: 'Category' },
  { id: 'price', accessorKey: 'price', header: 'Price', meta: { cell: { variant: 'currency', currency: 'USD' } } },
  { id: 'image', accessorKey: 'image', header: 'Image' }
];

export function ProductGallery({ products }: { products: Array<Product> }) {
  const [cardConfig, setCardConfig] = useState<DataGalleryCardConfigSerializable>({
    titleField: 'name',
    subtitleField: 'category',
    coverImageField: 'image',
    bodyFields: ['price'],
    variant: 'product'
  });
  const gallery = useDataGallery<Product>({
    data: products,
    columns,
    enableSearch: true,
    enableRowSelection: true,
    getRowId: row => row.id,
    displayConfig: { cardVariant: 'product', coverStyle: 'top-lg' }
  });

  return (
    <View className="flex-1">
      <DataGalleryToolbar
        table={gallery.table}
        displayConfig={gallery.displayConfig}
        onDisplayConfigChange={gallery.setDisplayConfig}
        cardConfig={cardConfig}
        onCardConfigChange={setCardConfig}
        enableCardConfig
        searchQuery={gallery.searchQuery}
        onSearchQueryChange={gallery.setSearchQuery} />
      <DataGallery
        {...gallery}
        cardConfig={cardConfig}
        onCardClick={record => openProduct(record.id)}
        actions={[{ key: 'archive', label: 'Archive', onAction: rows => archive(rows) }]} />
    </View>
  );
}

Interaction model

• Tap a card → onCardClick(record, rowIndex).
• Long-press a card → toggle its selection (when row selection is enabled). While cards are selected a bottom selection bar shows the count, Select all, your actions and a clear button (web: floating ActionBar).
• Pull to refresh → onRefresh; reaching the end → onEndReached (infinite paging).
• The column count follows displayConfig.columnCount, clamped so each card is at least minCardWidth wide — one column on phones, more on tablets.

API Reference

useDataGallery

useDataGallery<TData>(options: UseDataGalleryProps<TData>) accepts every TanStack TableOptions<TData> (except pageCount / getCoreRowModel) plus:

Return value (UseDataGalleryReturn<TData>):

DataGallery

DataGalleryAction<TData>: key?, label, icon?: ReactNode, variant?: 'default' | 'destructive', onAction?(rows), render?(rows).

DataGalleryToolbar

DataGallerySearch

DataGalleryCard

DataGalleryDisplayConfig

DataGalleryCardConfig

Serializable slots (DataGalleryCardConfigSerializable): titleField, descriptionField, subtitleField, avatarField, coverImageField, badgeField, timelineField (column ids), bodyFields, footerFields (column id arrays), variant. Render hooks: renderCard({ record, rowIndex, isSelected, onToggleSelected }), renderCover({ record, value }), renderAvatar({ record, value }), renderBadge({ record, value }), renderTimeline({ record, value }), renderActions({ record, rowIndex }).

Components

Exports

Type Exports

Native deltas

• FlashList with numColumns replaces @tanstack/react-virtual; the width is measured with onLayout (web: ResizeObserver). containerRef / virtualizer are gone; dir, estimatedCardHeight, overscan are accepted and ignored.
• Long-press selects (no hover checkbox); the selection bar is the grid's bottom bar.
• Toolbar = search on top + one horizontally scrollable row of chips opening bottom sheets.
• Additions: onRefresh / refreshing, onEndReached, emptyText, onContainerLayout.

Translation keys

ui.dataGallery.addCard, add, searchPlaceholder, emptyTitle, emptyDescription, emptyFilteredTitle, emptyFilteredHint, clearFilters (web keys), plus the grid's ui.dataGrid.selectAll / clearSelection for the selection bar.