DataGrid

Installation

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

pnpm add @tanstack/react-table @shopify/flash-list react-native-svg jsonata @react-querybuilder/core expo-clipboard (optional)

The native grid mirrors the web API 1:1: a headless controller (useDataGrid) owns the TanStack table and all grid state, and DataGrid renders whatever it returns. Mobile idioms replace desktop ones — editors open in bottom sheets, long-press enters selection mode, long-press on a header opens the column actions, and rows are virtualized with FlashList v2.

Usage

Headless (recommended — same as web)

import {
  DataGrid,
  DataGridToolbar,
  getDataGridSelectColumn,
  useDataGrid,
  type ColumnDef
} from '@/components/docyrus-native/data-grid';

type Employee = { id: string; name: string; status: string; salary: number; hireDate: string };

const columns: ColumnDef<Employee>[] = [
  getDataGridSelectColumn<Employee>(),
  { accessorKey: 'name', header: 'Name', size: 160, meta: { label: 'Name', cell: { variant: 'short-text' } } },
  {
    accessorKey: 'status',
    header: 'Status',
    meta: {
      label: 'Status',
      cell: {
        variant: 'status',
        options: [
          { label: 'Active', value: 'active', color: 'green' },
          { label: 'On Leave', value: 'on-leave', color: 'amber' },
          { label: 'Sick', value: 'sick', parent: 'on-leave', forceDescription: true },
          { label: 'Closed', value: 'closed', isFinalOption: true, forceFollowupDate: true }
        ]
      }
    }
  },
  { accessorKey: 'salary', header: 'Salary', meta: { label: 'Salary', cell: { variant: 'currency', currency: 'USD' } } },
  { accessorKey: 'hireDate', header: 'Hire date', meta: { label: 'Hire date', cell: { variant: 'date' } } }
];

export function EmployeesGrid() {
  const [data, setData] = useState<Employee[]>(initialRows);

  const grid = useDataGrid({
    data,
    columns,
    getRowId: row => row.id,
    onDataChange: setData,
    enableSearch: true,
    enableChangeTracking: true,
    onChangesSave: async (changes) => api.updateMany(changes),
    pagingMode: 'standard',
    pageSize: 50,
    rowColorRules: [{ formula: 'status = "closed"', color: 'red-100' }],
    initialState: { columnPinning: { left: ['select', 'name'] } },
    onRowsDelete: rows => api.delete(rows.map(row => row.id)),
    meta: {
      onStatusUpdate: input => api.statusUpdate(input),
      onOpenRelation: ({ relatedId }) => router.push(`/records/${relatedId}`)
    }
  });

  return (
    <View className="flex-1">
      <DataGridToolbar table={grid.table} />
      <DataGrid {...grid} actions={[{ label: 'Archive', onAction: rows => archive(rows) }]} />
    </View>
  );
}

Convenience (data + columns, native-only)

Without a table prop, DataGrid creates the controller internally. Every useDataGrid option is accepted, plus the legacy controlled sorting / columnFilters pairs and onDataUpdate.

<DataGrid data={tasks} columns={taskColumns} onDataChange={setTasks} stretchColumns height={320} />

Interaction model

useDataGrid

function useDataGrid<TData>(options: UseDataGridProps<TData>): UseDataGridReturn<TData>;

Options

Every TanStack TableOptions<TData> key (except getCoreRowModel / pageCount) is spread into the table — data, columns, getRowId, state, initialState, onColumnVisibilityChange, onColumnOrderChange, onColumnPinningChange, onColumnSizingChange, onGroupingChange, onExpandedChange, onPaginationChange, manualPagination, manualSorting, manualFiltering, rowCount, enableRowSelection, meta, … sorting, columnFilters and rowSelection are grid-owned (read state.* when supplied, else internal) and their on*Change callbacks receive the resolved value.

Return value

TableMeta

tableMeta spreads options.meta and adds the grid-owned members. Supply the host-side members through meta.

DataGrid

DataGridProps<TData> = DataGridHeadlessProps<TData> | DataGridConvenienceProps<TData>.

Props (headless — spread useDataGrid())

Props (convenience — no table)

All useDataGrid options plus every view prop above, and:

DataGridAction

Cell variants (CellOpts)

Columns whose header is a function (e.g. getDataGridSelectColumn, getDataGridActionsColumn) render through flexRender, like web. Column width is the TanStack size (falls back to the deprecated meta.width).

Toolbar & menus

Every menu is a compact chip that opens a bottom sheet (web: popover / dropdown). All take table and the common props below unless noted.

DataGridSidePanel

Container for useDocyrusDataGrid's vertical-tabs view picker (sidePanel). Web renders a fixed <aside> column; native is a full-width strip on phones (the vertical-tabs DataGridViewSelect opens its view list as a bottom sheet) and a side column on tablets.

Components

Exports

Type Exports

Translation keys

Copy goes through useUiTranslation() with the web ui.dataGrid.* keys (addRow, emptyTitle, emptyFilteredTitle, clearFilters, selectAll, selectRow, clearSelection, contextMenuDeleteRows, contextMenuClear, save, saving, cancel, item, itemsChanged, changesPending, cellEmpty, searchStatus, noStatusFound, statusNote, statusFollowup, statusUpdateFailed, openRelation, copyId, copyFailed, copiedToClipboard, sortAsc, sortDesc, removeSort, pinToLeft, unpinFromLeft, moveColumnLeft, moveColumnRight, groupByColumn, showAutonumber, hideColumn, tableView, galleryView, pagination.*) plus ui.common.cancel, ui.emailComposer.compose, ui.instantMessageComposer.compose, ui.formField.fileSource*. Native-only keys: ui.dataGrid.searchOptions, noOptions, call, openLink, edit, tapToEdit, rowDetails, rowCount.

Migration from the previous native DataGrid

• Headless first. useDataGrid + <DataGrid {...grid} /> is the primary API. <DataGrid data columns /> still works (convenience path).
• Built-in toolbar removed. The grid no longer renders its own filter / sort / group / row-height / display toolbar — compose DataGridToolbar and the menus above it. enableSearch renders the find bar (web find-in-grid) instead of a client globalFilter.
• Row tap calls tableMeta.onRowClick when supplied, else opens the editor sheet for editable cells, else the row detail sheet (email / phone / url cells open the contact sheet; checkbox / switch toggle in place). Long-press still selects.
• Summary chips ("N rows" / mode) are opt-in via showSummary.
• DataGridProps / DataGridAction moved from types.ts to data-grid.tsx (still exported from the barrel). DataGridAction.onAction is optional and receives (rows, rowIndices?).
• onRowsDelete(rows, indices) is now wired (selection bar Delete). onDataUpdate receives a single update or an array.
• rowHeight adds 'extra-tall'; height accepts 'auto'; the default is now fill-parent instead of intrinsic.
• Column width: use TanStack size; meta.width is a deprecated fallback.
• Date / number cells format through DateFormatProvider / NumberFormatProvider (or tableMeta.format*) — no more toISOString() output.
• DataGridCell accepts rowHeight as a preset or pixels and optional tableMeta / row / columnId.
• sparkline is a deprecated alias of { variant: 'chart', chartType: 'sparkline' }.
• The old internal components/* files and lib/data-grid-utils.ts were removed.