useDocyrusDataTable

Installation

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

Overview

useDocyrusDataTable is the table-flavored sibling of useDocyrusDataGrid. It produces a TanStack Table instance + toolbar wired to the same Docyrus saved-views, filter, and items endpoints, but renders rows through <DataTable> instead of <DataGrid>.

It also generates ColumnDefs automatically from the data source's field metadata, mapping every Docyrus field type to the matching value renderer.

Backend connection

Same three modes as useDocyrusDataGrid (precedence top→bottom):

1. data — pre-resolved array.
2. collection — TanStack DB collection from @docyrus/tanstack-db-generator.
3. Default — GET /v1/apps/:appSlug/data-sources/:dataSourceSlug/items via the @docyrus/api-client you pass as client.

The reload button refetches the items query (modes 2 and 3), the data source + views queries, and any onReload callback you provided.

Tenant-aware formatting

Date / datetime / number cells render through the formatters supplied by <DocyrusTenantProvider> — no per-table wiring required. Mount the provider once near the root of your app and every useDocyrusDataTable call below it picks up the tenant's dateFormat, dateTimeFormat, decimalSeparator, thousandSeparator, decimalPrecision, and timeZone settings automatically.

Resolution order for each cell formatter: explicit prop on useDocyrusDataTable({ formatDate, formatDateTime, formatNumber }) → surrounding useDateFormat() / useNumberFormat() context → cell's own legacy fallback. Apps that haven't adopted <DocyrusTenantProvider> keep their previous behaviour byte-for-byte.

Query parameters sent to the backend

The hook builds a ZodSelectQueryPayload-shaped payload (resolvedListParams) automatically from the active view + the toolbar search input + the optional side-panel filter rail + any listParams overrides:

The fully-resolved payload is exposed back to the consumer as resolvedListParams.

Usage

'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { DataTable } from '@docyrus/ui/components/data-table';
import { useDocyrusDataTable } from '@docyrus/ui/library/hooks/use-docyrus-data-table';

type OrganizationRow = { id: string; name: string };

export function OrganizationsTable() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const { table, tableProps, toolbar } = useDocyrusDataTable<OrganizationRow>({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'organization'
  });

  return (
    <div className="flex h-full flex-col gap-3">
      {toolbar}
      <DataTable table={table} {...tableProps} />
    </div>
  );
}

API Reference

Parameters

The hook accepts every option from useDocyrusDataViewSelect, plus:

Return Value

Side panel filters

When enableSideFilters is true, the hook renders a <DataTableSideFilters> rail alongside the table. The panel emits a RuleGroupType whenever the user adjusts a filter; the hook ANDs it onto the saved view's filterQuery and any toolbar filter menu rules before sending the items request — so side filters, toolbar filters, and the saved view all stack.

The toolbar filter menu (enableFilterMenu) is not auto-hidden; both can be active at the same time.

Collapse / expand

• sideFiltersDefaultExpanded controls the initial state. Default true.
• When expanded, a panel-close icon (top right of the panel header) collapses it to a vertical rail.
• When collapsed, the rail shows a 90°-rotated "Filters" label (with the active-filter count appended) that re-expands the panel on click.
• For controlled collapse state, pass sideFiltersExpanded + onSideFiltersExpandedChange.

DocyrusDataTableSideFiltersConfig<TData>

Usage

'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { DataTable } from '@docyrus/ui/components/data-table';
import { useDocyrusDataTable } from '@docyrus/ui/library/hooks/use-docyrus-data-table';
import { createColumnConfigHelper } from '@docyrus/ui/components/data-table-filter';

type OrganizationRow = { id: string; name: string; status: 'active' | 'archived' };

const dtf = createColumnConfigHelper<OrganizationRow>();

const sideFilterColumns = [
  dtf
    .text()
    .id('name')
    .accessor(row => row.name)
    .displayName('Name')
    .build(),
  dtf
    .option()
    .id('status')
    .accessor(row => row.status)
    .displayName('Status')
    .options([
      { value: 'active', label: 'Active' },
      { value: 'archived', label: 'Archived' }
    ])
    .build()
] as const;

export function OrganizationsTable() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const {
    table, tableProps, toolbar, sideFilters
  } = useDocyrusDataTable<OrganizationRow>({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'organization',
    enableSideFilters: true,
    sideFiltersDefaultExpanded: true,
    sideFiltersWidth: 280,
    sideFiltersConfig: {
      columnsConfig: sideFilterColumns,
      strategy: 'server',
      defaults: {
        status: { mode: 'inline-checkbox' }
      }
    }
  });

  return (
    <div className="flex h-full flex-col gap-3">
      {toolbar}
      <div className="flex flex-1 min-h-0">
        {sideFilters}
        <DataTable table={table} {...tableProps} className="flex-1" />
      </div>
    </div>
  );
}