Filters

A comprehensive filtering system with multiple filter types, operators, and visual indicators for data organization.

Priority

[
  {
    "id": "1770839009500-4bf4s1whi",
    "field": "priority",
    "operator": "is_any_of",
    "values": [
      "low",
      "medium",
      "critical"
    ]
  }
]

"use client"

import { useCallback, useState } from "react"

Installation


pnpm dlx shadcn@latest add @reui/filters

Usage

import {
  createFilter,
  Filters,
  type Filter,
  type FilterFieldConfig,
} from "@/components/reui/filters"

const [filters, setFilters] = useState<Filter[]>([
  createFilter("priority", "is_any_of", ["low", "medium"]),
])
 
const fields: FilterFieldConfig[] = [
  {
    key: "priority",
    label: "Priority",
    type: "multiselect",
    options: [
      { value: "low", label: "Low" },
      { value: "medium", label: "Medium" },
      { value: "high", label: "High" },
    ],
  },
]
 
return <Filters filters={filters} fields={fields} onChange={setFilters} />

Examples

Validation

"use client"

import { useCallback, useState } from "react"

Trigger Button

Assignee

"use client"

import { useCallback, useState } from "react"

Small Size

Priority

"use client"

import { useCallback, useState } from "react"

Large Size

Priority

"use client"

import { useCallback, useState } from "react"

Custom Controls

Date Range

"use client"

import { useCallback, useEffect, useMemo, useState } from "react"

Data Grid

Status

			Status	Availability
AJ Alex Johnson alex@apple.com	Apple	CEO	Active	Online	San Francisco, USA	$5,143.03
AJ Alex Johnson alex@vale.br	Vale	Software Engineer	Active	Busy	Rio de Janeiro, Brazil	$9,421.5
AT Aron Thompson aron@keenthemes.com	Keenthemes	Director	Active	Away	Kuala Lumpur, MY	$6,214.22
DK David Kim david@sap.com	SAP	Lawyer	Active	Online	Berlin, Germany	$9,876.54
EW Emma Wilson emma@tesla.com	Tesla	Developer	Inactive	Offline	Sydney, Australia	$3,456.45

Rows per page

1 - 5 of 12

Async Mode: Simulated API Delay of 800-2000ms

"use client"

import { useCallback, useEffect, useMemo, useRef, useState } from "react"

Nuqs

			Status	Availability
AJ Alex Johnson alex@apple.com	Apple	CEO	Active	Online	San Francisco, USA	$5,143.03
AJ Alex Johnson alex@vale.br	Vale	Software Engineer	Active	Busy	Rio de Janeiro, Brazil	$9,421.5
AT Aron Thompson aron@keenthemes.com	Keenthemes	Director	Active	Away	Kuala Lumpur, MY	$6,214.22
DK David Kim david@sap.com	SAP	Lawyer	Active	Online	Berlin, Germany	$9,876.54
EW Emma Wilson emma@tesla.com	Tesla	Developer	Inactive	Offline	Sydney, Australia	$3,456.45

Rows per page

1 - 5 of 12

Async Mode: Simulated API Delay of 800-2000ms

"use client"

import { useCallback, useEffect, useMemo, useRef, useState } from "react"

With i18n Support

Estado

"use client"

import { useCallback, useMemo, useState } from "react"

API Reference

Filters

The main component for displaying and managing a collection of active filters.

Prop	Type	Default	Description
`filters`	`Filter<T>[]`	-	`Required`. The array of active filters.
`fields`	`FilterFieldsConfig<T>`	-	`Required`. The configuration for available filter fields.
`onChange`	`(filters: Filter<T>[]) => void`	-	`Required`. Callback fired when filters are added, updated, or removed.
`size`	`"sm" \| "default" \| "lg"`	`"default"`	The size of the filter items and controls.
`trigger`	`ReactNode`	-	Custom element to trigger the "Add Filter" menu.
`showSearchInput`	`boolean`	`true`	Whether to show the search input in the "Add Filter" menu.
`allowMultiple`	`boolean`	`true`	Whether to allow multiple filters for the same field.
`enableShortcut`	`boolean`	`false`	Whether to enable the keyboard shortcut to open the filter menu.
`shortcutKey`	`string`	`"f"`	The key used for the shortcut (e.g., "f").
`shortcutLabel`	`string`	`"F"`	The label to display in the shortcut indicator.
`i18n`	`Partial<FilterI18nConfig>`	-	Custom labels and operators for internationalization.
`className`	`string`	-	Additional CSS classes for the container.
`menuPopupClassName`	`string`	-	Additional CSS classes for the filter dropdown menu.

FilterFieldConfig

Configuration for an individual filterable field.

Property	Type	Description
`key`	`string`	`Required`. Unique identifier for the field.
`label`	`string`	`Required`. Human-readable label for the field.
`type`	`"text" \| "select" \| "multiselect" \| "custom" \| "separator"`	The type of filter input to use.
`icon`	`ReactNode`	Optional icon to display next to the field label.
`options`	`FilterOption<T>[]`	List of options for `select` and `multiselect` fields.
`operators`	`FilterOperator[]`	Custom operators for this specific field.
`defaultOperator`	`string`	The operator to select by default when adding this field.
`placeholder`	`string`	Placeholder text for text inputs.
`searchable`	`boolean`	Whether the options list should be searchable.
`maxSelections`	`number`	Maximum number of items allowed in `multiselect`.
`prefix`	`ReactNode \| string`	Prefix element for the input field.
`suffix`	`ReactNode \| string`	Suffix element for the input field.
`pattern`	`string`	Regex pattern for text input validation.
`validation`	`(value) => boolean \| object`	Custom validation function.
`customRenderer`	`(props) => ReactNode`	Custom renderer for the filter value selector.
`customValueRenderer`	`(values, options) => ReactNode`	Custom renderer for the active filter value display.
`fields`	`FilterFieldConfig<T>[]`	Nested fields if this is a group configuration.
`group`	`string`	Group label if this is a group configuration.
`className`	`string`	Additional CSS classes for the field components.

FilterOption

Structure for options in select and multiselect fields.

Property	Type	Description
`value`	`T`	`Required`. The internal value of the option.
`label`	`string`	`Required`. Human-readable label for the option.
`icon`	`ReactNode`	Optional icon to display next to the option.
`className`	`string`	Additional CSS classes for the option item.

Filter

The structure of an active filter object.

Property	Type	Description
`id`	`string`	Unique identifier for the filter instance.
`field`	`string`	The `key` of the associated field configuration.
`operator`	`string`	The selected operator (e.g., "is", "contains").
`values`	`T[]`	The current value(s) of the filter.

FilterI18nConfig

Configuration for internationalization and custom labels.

Property	Type	Description
`addFilter`	`string`	Label for the "Add Filter" button.
`searchFields`	`string`	Placeholder for the field search input.
`operators`	`object`	Map of operator keys to localized strings.
`validation`	`object`	Map of validation error messages.
`placeholders`	`object`	Map of dynamic placeholder templates.

Helpers

Function	Signature	Description
`createFilter`	`(field, operator?, values?) => Filter`	Creates a new filter object with a unique ID.
`createFilterGroup`	`(id, label, fields, initialFilters?) => FilterGroup`	Creates a filter group configuration.

File Upload Frame

On This Page

Installation Usage Examples Validation Trigger Button Small Size Large Size Custom Controls Data Grid Nuqs With i18n Support API Reference Filters FilterFieldConfig FilterOption Filter FilterI18nConfig Helpers