useDocyrusPivotGrid
Pivot grid backed by a Docyrus data source. Aggregates on the device from raw records, or in the database through a pivot matrix and calculations, and returns a controller for the native PivotGrid components.
Installation
pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-docyrus-pivot-gridpnpm add @docyrus/api-client @tanstack/react-queryA straight port of the web hook, with the same signature. It fetches /v1/apps/{appSlug}/data-sources/{dataSourceSlug}/items through TanStack Query and feeds the rows into the native usePivotGrid. The result's controller plugs into PivotGridView, PivotGridToolbar, PivotGridExportMenu and PivotGridDrilldownModal. It needs an authenticated RestApiClient and a QueryClientProvider above it.
Two aggregation modes are available:
'client'(default): fetches raw records (columnsis auto-derived from the dimensions and measures,limitdefaults to 5000) and aggregates on the device. Simple, but not suited to large datasets.'server': sends apivot.matrix+calculationspayload so the database aggregates. The response has one row per dimension combination, so it scales to any dataset size. A date dimension withdateFormatis bucketed on the server withto_char[format]@fieldover adateRangeaxis.
Usage
import { useMemo } from 'react';
import { View } from 'react-native';
import { useDocyrusClient } from '@docyrus/signin/react-native';
import {
PivotGridDrilldownModal,
PivotGridToolbar,
PivotGridView
} from '@/components/docyrus-native/pivot-grid';
import { useDocyrusPivotGrid } from '@/hooks/docyrus-native/use-docyrus-pivot-grid';
export function TimeEntryReport() {
const client = useDocyrusClient();
const rowDimensions = useMemo(() => [
{ id: 'user', label: 'User', field: 'record_owner', subField: 'name', emptyLabel: 'Unassigned' }
], []);
const columnDimensions = useMemo(() => [
{
id: 'month',
label: 'Month',
field: 'date',
dateFormat: 'YYYY-MM',
dateRange: { interval: 'day', min: '2026-01-01', max: '2026-06-30' }
}
], []);
const measures = useMemo(() => [
{ id: 'logged', label: 'Logged (h)', field: 'duration', aggregate: 'sum' as const, transform: (s: number) => s / 3600 }
], []);
const { controller, isLoading, error, refetch } = useDocyrusPivotGrid({
client: client!,
appSlug: 'base',
dataSourceSlug: 'time_entry',
mode: 'server',
rowDimensions,
columnDimensions,
measures,
height: 420,
enabled: Boolean(client)
});
return (
<View className="gap-3">
<PivotGridToolbar controller={controller} />
<PivotGridView controller={controller} />
<PivotGridDrilldownModal controller={controller} />
</View>
);
}Memoize rowDimensions, columnDimensions and measures. They are part of the query payload and the pivot structure, so new arrays on every render rebuild both.
API Reference
Options (UseDocyrusPivotGridOptions<TData>)
| Option | Type | Default | Description |
|---|---|---|---|
client | RestApiClient | — | Authenticated API client. Required. |
appSlug | string | — | App slug of the data source. Required. |
dataSourceSlug | string | — | Data source slug. Required. |
mode | 'client' | 'server' | 'client' | Where to aggregate. |
rowDimensions | DocyrusPivotGridDimension<TData>[] | — | Row grouping dimensions (outermost → innermost). Required. |
columnDimensions | DocyrusPivotGridDimension<TData>[] | — | Column grouping dimensions. Required. |
measures | DocyrusPivotGridMeasure<TData>[] | — | Measures aggregated in each cell. Required. |
columns | string | auto | columns expression. In client mode it is auto-derived from the dimensions and measures (relation dimensions become ...field(subField)). In server mode the default is 'id'. |
filters | unknown | — | Server-side filters forwarded verbatim. |
orderBy | string | — | orderBy expression. Client mode only. |
limit | number | 5000 | Maximum records fetched. Client mode only. |
getRowId | (row: TData, index: number) => string | — | Stable row id forwarded to usePivotGrid. |
initialState | Partial<PivotGridState> | — | Initial expand, pin and size state. |
cellColorRules | PivotGridCellColorRule[] | — | JSONata cell color rules. |
drilldown | PivotGridDrilldown<TData> | — | Drilldown configuration (NativeDrilldownColumn columns). |
height | number | 'auto' | 600 | Grid height in px. Native has no auto height (the list is virtualized), so 'auto' resolves to 600. |
className | string | — | Container classes, applied by PivotGridView. |
exportFileName | string | 'pivot-grid' | Native only. Base file name for CSV, Excel and PDF exports. |
enabled | boolean | true | Enable the query. It also waits for client, appSlug and dataSourceSlug. |
staleTime | number | 30_000 | TanStack Query stale time in ms. |
The query key is ['docyrus', 'pivot-grid', mode, appSlug, dataSourceSlug, payload].
DocyrusPivotGridDimension
| Field | Type | Description |
|---|---|---|
id | string | Unique id. In server mode the column alias is dim_<id>. |
label | string | Header label. |
field | string | Field slug on the data source. |
subField | string | Sub-field of a relation (for example 'name' for record_owner.name). |
dateFormat | string | Server mode. Postgres to_char format ('YYYY-MM', 'YYYY') for date bucketing. |
dateRange | { interval: string; increment?: number; min: string; max: string } | Needed with dateFormat. The date axis passed to the pivot matrix. |
getValue | (row: TData) => unknown | Custom value extractor. Takes precedence over the automatic accessor. |
formatValue | (value: unknown) => string | Label formatter. |
sort | (a: unknown, b: unknown) => number | Sort comparator. |
emptyLabel | string | Label for empty values. |
DocyrusPivotGridMeasure
| Field | Type | Description |
|---|---|---|
id | string | Unique id. Also the server calculation alias. |
label | string | Header label. |
field | string | Field to aggregate ('id' for count). |
aggregate | 'sum' | 'count' | 'avg' | 'min' | 'max' | Aggregation function. |
transform | (value: number) => number | Applied after reading the value (for example seconds → hours). |
getValue | (row: TData) => number | null | undefined | Custom extractor. Takes precedence over field. |
formatValue | (value: number) => string | Cell formatter. |
Result (UseDocyrusPivotGridResult<TData>)
| Field | Type | Description |
|---|---|---|
controller | PivotGridController<TData> | Pass it to PivotGridView, PivotGridToolbar, PivotGridExportMenu and PivotGridDrilldownModal. |
items | TData[] | Rows returned by the API: raw records in client mode, aggregated rows in server mode. |
isLoading | boolean | First load in progress. |
isFetching | boolean | Any fetch in progress (including refetches). |
error | Error | null | Query error. |
refetch | () => void | Refetch the items. |
Differences from web
heightis a pixel value.'auto'falls back to600.classNameis forwarded through the controller and applied byPivotGridView.drilldown.columnsareNativeDrilldownColumns ({ id, header, getValue }) instead of TanStackColumnDefs.- Adds
exportFileNamefor the share-sheet exports.
Type Exports
| Type | Description |
|---|---|
UseDocyrusPivotGridOptions | Hook options. |
UseDocyrusPivotGridResult | Hook result. |
DocyrusPivotGridDimension | Docyrus-field dimension descriptor. |
DocyrusPivotGridMeasure | Docyrus-field measure descriptor. |
DocyrusPivotGridMode | 'client' | 'server'. |
PivotRow | Record<string, unknown> (default row type). |
PivotGridAggregate | Re-exported aggregate union. |
useDocyrusPivotFilter
Connects a Docyrus data source to a native PivotFilter strip. It detects the field type, runs a pivot aggregate query, builds pill items and date buckets, and emits filter rules. DocyrusPivotFilterGroup stacks several strips that cross-filter each other.
useDocyrusTenant
Tenant integration for Docyrus native apps. Fetches tenant preferences, builds dateUtils and numberUtils, and wires DateFormatProvider and NumberFormatProvider so every native component picks up the tenant's date and number formats.