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.

Edit on GitHubEditllms.txt

iOSAndroidExpo Go

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-docyrus-pivot-filter

Required Packages(4 packages)

pnpm add @docyrus/app-utils @docyrus/api-client @tanstack/react-query date-fns

This is a straight port of the web hook, with the same signature and the same query payloads. It needs an authenticated RestApiClient and a QueryClientProvider above it. The hook:

loads the data source schema (createDataSourceClient(client).getBySlug(app, ds, { expand: 'enums' }))
detects the field strategy from field.type
sends a native Docyrus pivot query to /v1/apps/{app}/data-sources/{ds}/items: columns: '<field>(id, name, icon, color)' for list fields, '<field>(id, name)' for users, '<bucket>@<field>' for dates, together with calculations
turns the rows into PivotFilterItems. Enum colours and icons come straight from the join. Date buckets are generated on the device, with Before, Upcoming and Not Set pills.
returns filterRule for the current selection and settingsContent (the PivotFilterSettings panel), which PivotFilter renders in a bottom sheet

Field type	Strategy	Filter rule emitted
`field-select`, `field-status`, `field-radioGroup`, `field-relation`	`list`	`{ field, operator: '=', value: id }`
`field-userSelect`	`user`	`{ field, operator: '=', value: userId }`
`field-date`	`date`	`between` with wall-clock bounds stamped `+00:00`
`field-dateTime`	`date`	`between` with the device's local offset
`field-multiSelect`, `field-tagSelect`, `field-userMultiSelect`	`unsupported`	none (query skipped)

The Not Set pill emits { operator: 'empty', value: null }. Before and Upcoming emit < and > against the window bounds.

Usage

Single strip

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

import { PivotFilter } from '@/components/docyrus-native/pivot-filter';
import { useDocyrusPivotFilter } from '@/hooks/docyrus-native/use-docyrus-pivot-filter';

export function TaskStatusFilter() {
  const client = useDocyrusClient();

  const pivot = useDocyrusPivotFilter({
    client: client!,
    appSlug: 'base',
    dataSourceSlug: 'task',
    fieldSlug: 'status'
  });

  // pivot.filterRule → AND it into your list query
  return <PivotFilter {...pivot.pivotFilterProps} totalLabel="All statuses" />;
}

DocyrusPivotFilterGroup

import { DocyrusPivotFilterGroup } from '@/hooks/docyrus-native/use-docyrus-pivot-filter';

<DocyrusPivotFilterGroup
  client={client}
  appSlug="base"
  dataSourceSlug="task"
  fields={[
    { fieldSlug: 'status', totalLabel: 'All statuses' },
    { fieldSlug: 'priority', totalLabel: 'All priorities' }
  ]}
  onFilterRuleChange={rule => setPivotRule(rule)} />

Each strip is fed the other strips' selections through activeFilters, so the counts react to what is selected elsewhere. onFilterRuleChange receives the AND of all selections, or null. On native, horizontal strips stack vertically with thin separators between them. With vertical, the rails sit side by side in a row (this suits tablets; on phones, prefer horizontal strips).

API Reference

Options (`UseDocyrusPivotFilterOptions`)

Option	Type	Default	Description
`client`	`RestApiClient`	—	Authenticated API client (required).
`appSlug`	`string`	—	App slug (required).
`dataSourceSlug`	`string`	—	Data source slug (required).
`fieldSlug`	`string`	—	Field to pivot on (required).
`calculation`	`PivotFilterCalculation \| null`	`null`	Initial aggregate; `null` = COUNT of `id`.
`defaultDateBucket`	`PivotFilterDateBucket`	`'days_of_week'`	Initial date bucket (date fields only).
`defaultFilters`	`unknown`	—	Base filter merged into every query (e.g. a saved view's filter).
`activeFilters`	`unknown`	—	The consumer's active filter. Pill counts react to it.
`parentPivotFilters`	`unknown`	—	Filter from a parent pivot (drill-down). A change resets the selection.
`hideZeroValues`	`boolean`	`false`	Hide items with a zero stat (except the selected one).
`defaultSelectedItemId`	`string \| null`	`null`	Initial selection.
`referenceDate`	`Date`	`new Date()`	Reference date for the date-bucket window.
`disableSettings`	`boolean`	`false`	Hide the settings sheet (`settingsContent` becomes `undefined`).
`onConfigurationChange`	`(config: { dateBucket: PivotFilterDateBucket; calculation: PivotFilterCalculation \| null }) => void`	—	Fired when the bucket or calculation changes.
`staleTime`	`number`	`30000`	TanStack Query `staleTime` (ms).
`enabled`	`boolean`	`true`	Skip fetching when `false`.
`dataSourceExpand`	`string \| false`	`'enums'`	`expand` param of the schema fetch. `false` or `''` omits it (core/tenant system data sources).

Date buckets (PivotFilterDateBucket): hours_of_today, days_of_week, days_of_month, weeks_of_month, weeks_of_quarter, months_of_quarter, months_of_year, quarters_of_year. Weeks start on Monday.

Result (`UseDocyrusPivotFilterResult`)

Field	Type	Description
`pivotFilterProps`	`PivotFilterProps`	Spread onto `<PivotFilter />` (items, selection, total, loading, hideZeroValues, onRefresh, settingsContent).
`items`	`PivotFilterItem[]`	Items built from the response.
`total`	`number`	Sum of all item stats.
`selectedItemId`	`string \| null`	Current selection (`null` = All).
`setSelectedItemId`	`(id: string \| null) => void`	Set the selection programmatically.
`selectedItem`	`PivotFilterItem \| null`	Selected item.
`filterRule`	`PivotFilterRule[] \| null`	Rule(s) for the selection; `null` for All.
`field`	`DataSourceField \| null`	Resolved field definition.
`fieldType`	`PivotFilterFieldType`	Strategy derived from `field.type`.
`dateBucket`	`PivotFilterDateBucket`	Current bucket.
`setDateBucket`	`(bucket: PivotFilterDateBucket) => void`	Change the bucket (also resets the selection).
`calculation`	`PivotFilterCalculation \| null`	Current calculation.
`setCalculation`	`(calc: PivotFilterCalculation \| null) => void`	Change the calculation.
`reload`	`() => void`	Invalidate the schema and refetch the items.
`isLoading`	`boolean`	First load of the schema or items.
`isFetching`	`boolean`	Any fetch in progress.
`error`	`Error \| null`	Schema or items error.

DocyrusPivotFilterGroupProps

Prop	Type	Default	Description
`client`	`RestApiClient`	—	Authenticated API client (required).
`appSlug`	`string`	—	App slug (required).
`dataSourceSlug`	`string`	—	Data source slug (required).
`fields`	`ReadonlyArray<DocyrusPivotFilterGroupField>`	—	One entry per strip, top to bottom (required).
`defaultFilters`	`unknown`	—	Base filter for every strip.
`activeFilters`	`unknown`	—	External filter for every strip (e.g. the list's toolbar filter).
`onFilterRuleChange`	`(rule: PivotFilterRule[] \| null) => void`	—	AND-combined rule of every selection.
`vertical`	`boolean`	`false`	Vertical rails side by side instead of stacked horizontal strips.
`compact`	`boolean`	`false`	Compact pills.
`className`	`string`	—	Wrapper `View` classes.
`staleTime`	`number`	—	Forwarded to every strip.
`dataSourceExpand`	`string \| false`	—	Forwarded to every strip.

DocyrusPivotFilterGroupField

Field	Type	Description
`fieldSlug`	`string`	Field to pivot on (required).
`defaultDateBucket`	`PivotFilterDateBucket`	Initial bucket for date fields.
`calculation`	`PivotFilterCalculation \| null`	Initial calculation.
`totalLabel`	`string`	"All" pill label for this strip.
`hideZeroValues`	`boolean`	Hide zero-stat items.
`disableSettings`	`boolean`	Hide the settings sheet for this strip.
`defaultSelectedItemId`	`string \| null`	Initial selection.

Translation keys

The hook reads ui.pivotFilter.notSet ("Not Set"), ui.pivotFilter.before ("Before") and ui.pivotFilter.upcoming ("Upcoming") through useUiTranslation(). For the component and settings-panel keys, see PivotFilter.

Differences from web

The settings content renders in a bottom sheet instead of a popover. Its aggregate-function and field pickers are chip rows instead of Selects.
DocyrusPivotFilterGroup puts a thin separator between horizontal strips.
PivotFilterAggregateFunc / PivotFilterCalculation / PivotFilterDateBucket / PivotFilterFieldType are declared in the component's types.ts and re-exported here under the same names.

Type Exports

Type	Description
`UseDocyrusPivotFilterOptions`	Hook options.
`UseDocyrusPivotFilterResult`	Hook result.
`DocyrusPivotFilterGroupProps`	Group component props.
`DocyrusPivotFilterGroupField`	Per-strip config of the group.
`PivotFilterRule`	`{ field, operator, value }`.
`PivotFilterAggregateFunc`	`'count' \| 'sum' \| 'avg' \| 'min' \| 'max'`.
`PivotFilterCalculation`	`{ func, field }`.
`PivotFilterDateBucket`	The 8 date buckets.
`PivotFilterFieldType`	`'list' \| 'user' \| 'user-multi' \| 'date' \| 'unsupported'`.

useDocyrusPivotFilter

On this page