DataTableSideFilters

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-data-table-side-filters

pnpm add @react-querybuilder/core date-fns tailwind-variants

DataTableSideFilters is built on the same ColumnConfig schema as DataTableFilter, so one column definition powers both the filter wizard and the facet panel. useDataTableSideFilters wraps useDataTableFilters and translates the internal FiltersState to and from a react-querybuilder RuleGroupType, so the emitted query feeds the Query Builder, saved views and your back end unchanged.

Usage

import { useState } from 'react';

import {
  DataTableSideFilters,
  useDataTableSideFilters,
  type RuleGroupType
} from '@/components/docyrus-native/data-table-side-filters';

const columnsConfig = [
  {
    id: 'category',
    displayName: 'Category',
    icon: 'fal bag-shopping',
    type: 'option' as const,
    accessor: (row: Product) => row.category,
    options: categoryOptions
  },
  {
    id: 'vendorId',
    displayName: 'Vendor',
    icon: 'fal user',
    type: 'multiOption' as const,
    accessor: (row: Product) => [row.vendorId],
    asyncOptions: {
      load: async ({ search, page, pageSize, signal }) => {
        const res = await fetch(`${API}/vendors?q=${search}&page=${page}&size=${pageSize}`, { signal });

        return res.json(); // → { items: ColumnOption[], hasMore: boolean }
      }
    }
  },
  {
    id: 'price',
    displayName: 'Price',
    icon: 'fal dollar-sign',
    type: 'number' as const,
    accessor: (row: Product) => row.price,
    min: 0,
    max: 500
  },
  {
    id: 'releasedAt',
    displayName: 'Released',
    icon: 'fal calendar',
    type: 'date' as const,
    accessor: (row: Product) => row.releasedAt
  },
  {
    id: 'inStock',
    displayName: 'In stock',
    icon: 'fal circle-check',
    type: 'boolean' as const,
    accessor: (row: Product) => row.inStock
  }
] as const;

export function ProductFilters({ products }: { products: Product[] }) {
  const [query, setQuery] = useState<RuleGroupType>({ combinator: 'and', rules: [] });

  const { columns, filters, actions, strategy } = useDataTableSideFilters({
    strategy: 'client',
    data: products,
    columnsConfig,
    query,
    onQueryChange: setQuery
  });

  return (
    <DataTableSideFilters
      columns={columns}
      filters={filters}
      actions={actions}
      strategy={strategy}
      title="Filter products"
      searchable="name" />
  );
}

Presentation

• presentation="sheet" (default): renders an outline Filters (n) button. Pressing it opens a large-detent ActionSheet with Clear all on the left and Done on the right. The search input and the active-filter chips sit in the sheet's fixed header, and the sections scroll below them. Filters apply live, so Done only closes the sheet. Replace the button with renderTrigger, and control visibility with open / defaultOpen / onOpenChange.
• presentation="inline": renders the panel in place (tablets, a dedicated filter screen). With collapsible, the header gets a collapse button and the collapsed state is a full-width bar (Filters · n) that expands on press.

<DataTableSideFilters
  {...filterProps}
  presentation="inline"
  variant="bordered"
  collapsible
  defaultExpanded={false} />

Render mode resolution

Each column picks its UI by column.type. You can override the mode with defaults[columnId].mode:

Set defaults[columnId].mode = 'dropdown-chips' to move a long static option list into a picker sheet.

Sections, sticky filters and Show more

<DataTableSideFilters
  {...filterProps}
  defaults={{
    inStock: { sticky: true },
    tags: { showMoreThreshold: 6 },
    rating: { collapsed: true },
    internalCode: { hidden: true }
  }}
  sections={[
    { id: 'shop', title: 'Shop', columnIds: ['category', 'brand', 'vendorId'] },
    { id: 'pricing', title: 'Pricing & Quality', columnIds: ['price', 'rating'] }
  ]} />

Without sections, sticky columns render first and the rest follow. With sections, columns you did not list fall into an Other group at the end.

Query JSON output

useDataTableSideFilters emits a RuleGroupType through onQueryChange whenever a filter changes, and returns it as query. Operators are mapped through DEFAULT_OPERATOR_MAP (for example contains → like, is between → between, is any of → in, include any of → contains any). Pass operatorMap to use a different vocabulary. Date values are serialized as timezone-naive yyyy-MM-dd'T'HH:mm:ss strings. For date-only columns, the start side is snapped to 00:00:00 and the end side to 23:59:59, so the whole boundary day is included.

API Reference

DataTableSideFiltersProps

useDataTableSideFilters options (DataTableSideFiltersOptions)

Extends the useDataTableFilters options (without defaultFilters / filters / onFiltersChange, which the hook owns).

The hook returns { columns, filters, actions, strategy, query, defaults, sections, reset }. reset() clears every filter.

SideFilterColumnDefaults

SideFilterSectionGroup

Building blocks

Native differences

• A persistent side column does not fit a phone, so the default presentation is a trigger plus a large bottom sheet. The web layout is available as presentation="inline".
• Numeric ranges use Min / Max inputs without a slider.
• Option pickers (dropdown-chips and async options) open a picker sheet instead of a popover.
• New native-only props: presentation, triggerLabel, renderTrigger, open, defaultOpen, onOpenChange, and layout on SideFilterActiveChips. collapsedWidth is accepted but ignored.
• Column icons are DocyrusIcon names (for example 'fal tag'), elements or components, instead of Lucide icons.

Translation keys

Panel strings use ui.dataTableSideFilters.* with English fallbacks: title, clearAll, clear, other, done, expand, collapse, any, selected, showMore, showLess, minMaxOrder, asyncNotConfigured. Filter-core strings (search, min / max, true / false, date presets) come from the ui.dataTableFilter.* keys shared with DataTableFilter.

Components

Helpers

Type Exports