PivotFilter

Installation

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

pnpm add react-native-reanimated react-native-gesture-handler tailwind-variants

PivotFilter only handles presentation. To connect it to a Docyrus data source, which covers the pivot query, pill items, date buckets, filter rules and settings content, use useDocyrusPivotFilter or DocyrusPivotFilterGroup for several strips that cross-filter each other.

Usage

import { useState } from 'react';

import { PivotFilter, type PivotFilterItem } from '@/components/docyrus-native/pivot-filter';

const items: PivotFilterItem[] = [
  { id: 'open', name: 'Open', stat: 24, color: 'sky', icon: 'fal circle' },
  { id: 'done', name: 'Done', stat: 1280, color: 'emerald', icon: 'fal circle-check' },
  { id: 'EMPTY', name: 'Not Set', stat: 3, isEmpty: true }
];

export function StatusFilter() {
  const [selected, setSelected] = useState<string | null>(null);

  return (
    <PivotFilter
      items={items}
      total={1307}
      selectedItemId={selected}
      onSelect={item => setSelected(item?.id ?? null)}
      onRefresh={() => refetch()} />
  );
}

Settings sheet

When you pass settingsContent, a gear button appears. Pressing it opens the content in a bottom sheet (ActionSheet, medium detent that expands to large). This replaces the web popover. The exported PivotFilterSettings panel holds the date-bucket and calculation controls that useDocyrusPivotFilter supplies on its own:

import { PivotFilter, PivotFilterSettings } from '@/components/docyrus-native/pivot-filter';

<PivotFilter
  {...props}
  settingsContent={(
    <PivotFilterSettings
      fieldType="date"
      dateBucket={bucket}
      onDateBucketChange={setBucket}
      calculation={calculation}
      onCalculationChange={setCalculation}
      aggregateFields={[{ slug: 'budget', name: 'Budget' }]} />
  )} />

Mobile behaviour

• Horizontal (default): a horizontally scrolling strip without a scroll indicator. The selected pill is scrolled to the centre whenever the selection or the content changes. The refresh and gear buttons sit at the start of the strip.
• Vertical: a full-width bordered column. The selected row gets an accent background and a left accent bar, and the toolbar sits along the top edge. On phones, prefer horizontal strips.
• The accent colour comes from item.color, a Tailwind family such as sky, a token such as emerald-500, or a hex value, resolved with resolveColorHex. Users render with Avatar, icons with DocyrusIcon, and loading renders SkeletonBase pills.
• Stats of 1000 or more render as 1.3k, and non-integers render with 2 decimals.

API Reference

PivotFilterProps

PivotFilterItem

PivotFilterUser

PivotFilterSettingsProps

The web panel uses two Selects for the aggregate function and the measure field. On native these are chip rows (SUM / AVG / MIN / MAX, then one chip per field), so a second sheet never opens on top of the settings sheet.

PivotFilterPillProps

Translation keys

The component reads these through useUiTranslation(), using the same keys as web: ui.pivotFilter.all, ui.pivotFilter.refresh, ui.pivotFilter.settings, ui.pivotFilter.empty. The settings panel uses ui.pivotFilter.dateFilterType, ui.pivotFilter.calculation, ui.pivotFilter.countOfRecords, ui.pivotFilter.function, ui.pivotFilter.field, ui.pivotFilter.noNumericFields, plus ui.pivotFilter.bucket.hoursOfToday | daysOfWeek | daysOfMonth | weeksOfMonth | weeksOfQuarter | monthsOfQuarter | monthsOfYear | quartersOfYear.

Components

Type Exports