useLocalDataSourceDataGrid

Wire a LocalDataSource object into the Docyrus DataGrid hook stack, including toolbar search, filters, sorting, grouping, saved views, and local CRUD.

Edit on GitHubEditllms.txt

Installation

pnpm dlx @docyrus/cli add @docyrus/hooks-use-local-data-source-data-grid

Required Packages(3 packages)

pnpm add @tanstack/react-query @tanstack/react-table jsonata

Overview

useLocalDataSourceDataGrid connects a LocalDataSource to the same grid workflow used by useDocyrusDataGrid. It gives local JSON data the standard Docyrus grid experience:

Automatic columns from local field metadata.
Toolbar search, filter, group, sort, row height, field visibility, display controls, and reload.
DataGridViewSelect with developer-provided systemViews.
Local list queries using the same filterKeyword, filters, formulas, calculations, orderBy, limit, and offset behavior exposed by LocalDataSource.list.
Inline change save and bulk delete/update through the local collection methods.

The hook disables server export by default because the records are local. Use useDataExport for browser-side export flows.

Usage

'use client';

import { useState } from 'react';

import { DataGrid, type SavedDataGridView } from '@docyrus/ui/components/data-grid';
import { useLocalDataSource } from '@docyrus/ui/library/hooks/use-local-data-source';
import { useLocalDataSourceDataGrid } from '@docyrus/ui/library/hooks/use-local-data-source-data-grid';

type Deal = {
  id: string;
  account: string;
  stage: string;
  amount: number;
  probability: number;
};

const fields = [
  { slug: 'id', name: 'ID', type: 'field-identity', readOnly: true },
  { slug: 'account', name: 'Account', type: 'field-text' },
  { slug: 'stage', name: 'Stage', type: 'field-select' },
  { slug: 'amount', name: 'Amount', type: 'field-money' },
  { slug: 'probability', name: 'Probability', type: 'field-percent' },
  { slug: 'weighted_amount', name: 'Weighted Amount', type: 'field-money', readOnly: true }
];

const views: Array<SavedDataGridView> = [
  {
    id: 'all',
    name: 'All',
    columnOrder: ['account', 'stage', 'amount', 'probability', 'weighted_amount'],
    columnVisibility: { id: false },
    columnPinning: { left: [], right: [] },
    sorting: [{ id: 'weighted_amount', desc: true }],
    isDefault: true
  },
  {
    id: 'active',
    name: 'Active',
    columnOrder: ['account', 'stage', 'amount', 'weighted_amount'],
    columnVisibility: {},
    columnPinning: { left: [], right: [] },
    filterQuery: {
      combinator: 'and',
      rules: [{ field: 'stage', operator: 'notIn', value: ['Closed Won', 'Closed Lost'] }]
    }
  }
];

export function LocalDealsGrid() {
  const [rows, setRows] = useState<Array<Deal>>([
    { id: '1', account: 'Northwind Labs', stage: 'Proposal', amount: 120000, probability: 0.6 },
    { id: '2', account: 'Contoso Finance', stage: 'Discovery', amount: 80000, probability: 0.35 }
  ]);

  const dataSource = useLocalDataSource<Deal>({
    id: 'local-deals',
    slug: 'deals',
    appSlug: 'local',
    name: 'Local Deals',
    data: rows,
    metadata: fields,
    onDataChange: setRows
  });

  const { table, gridProps, toolbar } = useLocalDataSourceDataGrid<Deal>({
    dataSource,
    systemViews: views,
    listParams: {
      columns: 'id, account, stage, amount, probability, weighted_amount',
      formulas: {
        weighted_amount: { jsonata: 'amount * probability' }
      },
      limit: 100
    },
    defaultRowGroupingColumn: 'stage',
    enableServerExportMenu: false
  });

  return (
    <div className="flex h-full flex-col gap-3">
      {toolbar}
      <DataGrid table={table} {...gridProps} height="auto" />
    </div>
  );
}

Relationship To useDocyrusDataGrid

useLocalDataSourceDataGrid is a small adapter over useDocyrusDataGrid:

It passes dataSource.client as the metadata/view client.
It passes local list, updateMany, and deleteMany methods as the grid collection.
It forwards almost every useDocyrusDataGrid option except client, appSlug, dataSourceSlug, collection, and listParams.
listParams uses the local query type from useLocalDataSource, so it can include JSONata formulas and local-only query fields.

Because it reuses useDocyrusDataGrid, the return value is the same shape: table, gridProps, toolbar, items, resolvedListParams, views, fields, activeViewId, reload, and side/pivot filter fields.

Stable Props

When using systemViews, listParams, toolbarStartContent, or toolbarEndContent, keep their references stable with module-level constants or useMemo. These values participate in view and table synchronization.

const listParams = useMemo(() => ({
  formulas: {
    weighted_amount: { jsonata: 'amount * probability' }
  },
  limit: 100
}), []);

const toolbarEndContent = useMemo(() => (
  <Button onClick={addRow}>Add row</Button>
), [addRow]);

useLocalDataSourceDataGrid({
  dataSource,
  listParams,
  systemViews,
  toolbarEndContent
});

API Reference

Parameters

useLocalDataSourceDataGrid(options) accepts:

Option	Type	Default	Description
`dataSource`	`LocalDataSource<TData>`	—	Local data source from `useLocalDataSource` or `createLocalDataSource`. Required.
`listParams`	`LocalDataSourceQueryParams`	—	Query params passed to `dataSource.list` after the active view/search/filter state is merged by `useDocyrusDataGrid`.
`systemViews`	`Array<SavedDataGridView>`	—	Developer-defined views shown in `DataGridViewSelect`. These are local and not persisted to a backend.
`defaultRowGroupingColumn`	`string`	—	Field slug used for initial grouping when the active view does not define grouping.
`enableServerExportMenu`	`boolean`	`false`	Server export menu is disabled by default for local data.
`...gridOptions`	`Omit<UseDocyrusDataGridOptions, 'client' \| 'appSlug' \| 'dataSourceSlug' \| 'collection' \| 'listParams'>`	—	All other supported `useDocyrusDataGrid` options, including toolbar toggles, column mapping, row actions, side filters, pivot filters, formatting, and change tracking.

Return Value

The hook returns UseDocyrusDataGridResult<TData>.

Property	Description
`table`	TanStack Table instance for `<DataGrid>`.
`gridProps`	Props to spread onto `<DataGrid>`.
`toolbar`	Pre-wired toolbar with view select, search, filters, grouping, sorting, fields, display, reload, and custom toolbar slots.
`items`	Current local rows returned by `dataSource.list`.
`resolvedListParams`	Merged local query params sent to `dataSource.list`.
`reload`	Refetch local rows and refresh view metadata.
`views` / `activeViewId` / `setActiveViewId`	Local/system view state exposed by the underlying data-grid view hook.

Playground

See the local demo in the playground at apps/playground/src/pages/local-data-source-page.tsx.

useLocalDataSourceDataGrid

On this page