# useDocyrusDataTable
URL: /docs/native/hooks/use-docyrus-data-table

Headless Docyrus-backed table for the native DataTable — schema columns rendered with the value renderers, server filters / sort / search / paging, saved views, bulk actions, exports and a table ↔ gallery view node.

## Installation

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

**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)
- [@react-querybuilder/core](https://react-querybuilder.js.org)

A port of the web hook with the same options and result. It builds its own `useReactTable` instance (no grid editing controller) whose cells render through the native value renderers, and returns `table` + `tableProps` for the headless native [rn-data-table](/docs/native/docyrus/data-table), a `toolbar`, and a `view` node that switches between the table and a card gallery. It shares the saved views, list-params, export and bulk-action engine with [`useDocyrusDataGrid`](/docs/native/hooks/use-docyrus-data-grid).

## Overview

- **Columns** — one column per schema field whose cell is the field's value renderer (`VALUE_RENDERER_MAP`); object values group by a stable key. `inferColumnsFromData` derives columns from the rows when there is no schema.
- **Items query** — `GET /v1/apps/{appSlug}/data-sources/{dataSourceSlug}/items` (or `collection.list`) with a flat `columns` list, `expand`, `orderBy` (sorting is manual for server data), `filters` (saved view + toolbar chips + `listParams.filters`), debounced `filterKeyword`, `limit` / `offset` / `fullCount` in standard paging.
- **Saved views** — `DataGridViewSelect` in the toolbar; the active view is applied like the grid hook (reserved columns pinned left). `pinLeadingColumns` pins `select` / `actions` / `__*` columns on view-less tables.
- **Display mode** — `enableDisplayMenu` adds the table / gallery toggle; `view` renders `DataTable` or the native `DataGridGallery` (legacy `cardConfig` adapted with `adaptLegacyCardConfig`, pull-to-refresh → records reload).
- **Bulk actions** — selection bar inside `toolbar` (`update` / `delete` / `export` / `email` / `message` + `extraBulkActions`).
- **Persistence** — `persistState` per active view (search, filters, sort, grouping, display mode, column layout, page size).

## Usage

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

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

import { useDocyrusDataTable } from '@/hooks/docyrus-native/use-docyrus-data-table';

export function OrganizationsTable() {
  const client = useDocyrusClient();
  const { toolbar, view } = useDocyrusDataTable({
    client: client!,
    appSlug: 'base',
    dataSourceSlug: 'organization',
    enableDisplayMenu: true,
    persistState: true,
    cardConfig: { titleField: 'name', descriptionField: 'email' },
    onRowClick: row => console.log(row.original)
  });

  return (
    
  );
}
```

Render `` yourself instead of `view` when you don't need the gallery toggle.

## API Reference

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

Every [`useDocyrusDataViewSelect`](/docs/native/hooks/use-docyrus-data-view-select#options-usedocyrusdataviewselectoptions) option is accepted and forwarded, plus:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `data` | `TData[]` | — | Pre-resolved rows (skips the items query; search filters client-side). |
| `collection` | `DocyrusDataGridCollection<TData>` | — | `{ list, updateMany?, deleteMany? }`. |
| `listParams` | `DocyrusDataGridListParams` | — | Extra items params (`filters` AND-merged). |
| `defaultLimit` | `number` | `100` | Default page size. |
| `enableItemsQuery` | `boolean` | `data === undefined` | Toggle the items query. |
| `pagingMode` | `'standard' \| 'virtual-scroll'` | view | Force the paging mode. |
| `pageSize` | `number` | view / `defaultLimit` | Standard-paging page size without a view. |
| `showSelectColumn` | `boolean` | `true` | Leading select column. |
| `enableRowNumbers` | `boolean` | `true` | Row numbers on the select column. |
| `selectColumn` / `actionsColumn` | `ColumnDef<TData>` | — | Replace the select column / add an actions column. |
| `extraColumns` | `ColumnDef<TData>[]` | — | Columns before the field columns. |
| `pinLeadingColumns` | `boolean` | `false` | Pin utility columns left when no view is active. |
| `mapColumn` | `(field, defaultColumn) => ColumnDef \| null` | — | Per-field override. |
| `inferColumnsFromData` | `boolean` | `false` | Columns from row keys when there's no schema. |
| `onRowClick` | `(row: Row<TData>) => void` | — | Row press (table) / card press (gallery). |
| `users` | `CellUserOption[]` | — | Users for the user filter options. |
| `getRelationHref` / `onOpenRelation` | relation navigation | — | Forwarded to `tableMeta`. |
| `formatDate` / `formatDateTime` / `formatNumber` | formatters | context | Tenant formatters (default: providers when mounted). |
| `initialState` | `Partial<{ sorting; columnFilters; columnVisibility; rowSelection; expanded; grouping; pagination }>` | — | Initial TanStack state. |
| `enableViewSelect` / `viewSelectVariant` / `viewSelectMaxVisible` | view picker | `true` / `'horizontal-tabs'` | View picker (`'vertical-tabs'` omits it on native). |
| `enableSearchInput` | `boolean` | `true` | Search input. |
| `searchPlaceholder` / `searchDebounceMs` | `string` / `number` | `t('ui.common.search', 'Search...')` / `300` | Search config. |
| `enableFilterMenu` / `enableGroupMenu` / `enableSortMenu` | `boolean` | `true` | Menu triggers. |
| `enableDisplayMenu` | `boolean` | `false` | Table / gallery toggle. |
| `defaultDisplayMode` | `'table' \| 'gallery'` | `'table'` | Initial display mode. |
| `displayMode` / `onDisplayModeChange` | controlled display mode | — | Controlled pair. |
| `cardConfig` | `DataGridCardConfig<TData>` | — | Gallery card config (`titleField`, `descriptionField`, `imageField`, `bodyFields`, `renderCard`). |
| `galleryHeight` | `number \| 'auto'` | `'auto'` | Gallery height (`'auto'` fills the parent). |
| `galleryClassName` | `string` | — | Gallery container classes. |
| `enableReloadButton` / `onReload` | reload | `true` | Records-only reload. |
| `enableServerExportMenu` | `boolean` | `true` | Server export menu. |
| `serverExportLimit` / `serverExportExcludedFieldTypes` / `serverExportExcludedSlugs` | export config | `10000` / internal | Server export. |
| `toolbarClassName` / `toolbarStartContent` / `toolbarEndContent` | toolbar | — | Toolbar customization. |
| `bulkActions` | `false \| DocyrusDataGridBulkAction[]` | all five | Selection actions. |
| `extraBulkActions` | `DataGridAction<TData>[]` | — | Appended selection actions. |
| `exportColumns` / `exportFileName` | export | `'visible'` / `dataSourceSlug` | Bulk export columns / file name. |
| `renderBulkUpdateDialog` / `renderEmailComposeDialog` / `renderMessageComposeDialog` | render slots | native dialogs | **Native.** Replace the default `BulkUpdateDialog` / `EmailComposeDialog` / `InstantMessageComposeDialog`. |
| `onBulkEmail` / `onBulkMessage` | callbacks | — | **Native.** Same as the grid hook; also used by email / phone cells. |
| `tableClassName` / `tableContainerClassName` / `emptyText` | `DataTable` props | — | Forwarded through `tableProps`. |
| `persistState` | `boolean \| { storage?; key? }` | — | Persist view parameters. |
| `enableSideFilters` | `boolean` | `false` | Render `sideFilters` and AND its rule group into the items query. |
| `sideFiltersConfig` | `DocyrusDataTableSideFiltersConfig<TData>` | — | Same shape as the grid hook's [`DocyrusDataGridSideFiltersConfig`](/docs/native/hooks/use-docyrus-data-grid#side-filters) (incl. native `presentation: 'sheet' \| 'inline'`). |
| `sideFiltersDefaultExpanded` | `boolean` | `true` | Initial expanded state of the inline panel. |
| `sideFiltersExpanded` / `onSideFiltersExpandedChange` | controlled state | — | Inline panel expanded state. |
| `sideFiltersWidth` | `number \| string` | `280` | Expanded inline panel width. |

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

All `useDocyrusDataViewSelect` result fields except `gridViewSelectProps`, plus:

| Field | Type | Description |
|-------|------|-------------|
| `table` | `Table<TData>` | TanStack table (`useReactTable`). |
| `tableProps` | `object` | `className`, `containerClassName`, `emptyText`, `pagination`, `isLoading`, `isReloading`, `onRowClick` — spread onto `DataTable` (minus `isReloading`). |
| `toolbar` | `ReactNode` | Controls + selection bar + bulk dialogs. |
| `view` | `ReactNode` | `DataTable` or the card gallery. |
| `displayMode` / `setDisplayMode` | `'table' \| 'gallery'` / setter | Current display mode. |
| `items` | `TData[]` | Rows. |
| `resolvedListParams` | `DocyrusDataGridListParams` | Params sent. |
| `pagingMode` | `'standard' \| 'virtual-scroll' \| undefined` | Resolved paging mode. |
| `reload` | `() => void` | Full refetch. |
| `sidePanel` | `ReactNode` | `DataGridSidePanel` with the vertical-tabs view picker (`viewSelectVariant === 'vertical-tabs'`), else `null`. |
| `sideFilters` | `ReactNode` | `DataTableSideFilters` (sheet trigger by default), or `null`. |
| `sideFiltersExpanded` / `setSideFiltersExpanded` | `boolean` / setter | Inline panel state. |
| `sideFiltersQuery` | `RuleGroupType \| undefined` | Rule group emitted by the side filters. |

## Native deltas

- `view` renders the native headless `DataTable` or the native `DataGridGallery` (FlashList of `DataGalleryCard`s, pull-to-refresh wired to the records reload).
- Email / phone value renderers open the native compose dialogs from `client` (like web); a host override (`onBulkEmail` / `renderEmailComposeDialog`, or the message pair) wins through `onComposeEmail` / `onSendMessage`.
- Bulk actions: same native engine as the grid hook (`update` / `email` / `message` open the native dialogs; `export` via ActionSheet + share sheet).
- User / relation option loaders resolve relation targets through the shared inventory (web table fetches `/v1/apps/data-sources`).
- Side filters default to a sheet trigger (`presentation: 'inline'` for the web column); the vertical-tabs `sidePanel` opens its view list as a bottom sheet on phones.

## Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusDataTableOptions` / `UseDocyrusDataTableResult` | Options / result. |
| `DocyrusDataTableSideFiltersConfig` | Side-filter config (parity). |