Filtration opens a panel of filter sections closed by Apply and Clear buttons. State is yours: each section wraps a controlled primitive.
When to use
Use Filtration above search results, tables, and service catalogs when users combine several criteria: status, region, date, category. Stage the changes and apply them together so the results do not jump after every click.
Use the inline panel on wide screens and the overlay on mobile. For a single filter, a Select or Chip row is enough.
Examples
Overlay filter (controlled)
Props
Props declared by Filtration. Native attributes of the underlying element pass through.
<Filtration>
| Prop | Type | Default | Description |
|---|
overlay | boolean | – | Floating overlay anchored to the trigger (default) vs an embedded inline panel. |
open | boolean | – | Controlled open state (overlay only). |
defaultOpen | boolean | – | Uncontrolled initial open state (overlay only). |
onOpenChange | (open: boolean) => void | – | |
children | react.ReactNode | – | |
<FiltrationTrigger>
| Prop | Type | Default | Description |
|---|
size | "sm" | "md" | "lg" | "icon" | "icon-md" | "icon-sm" | "icon-xs" | – | |
fullWidth | boolean | – | |
onColor | boolean | – | |
loading | boolean | – | |
startIcon | react.ReactNode | – | Leading icon. For an icon-only button pass the glyph as children with an icon size and an aria-label. |
endIcon | react.ReactNode | – | |
iconFlip | boolean | – | Flip start/end icons horizontally in RTL (for chevrons, arrows, etc.) |
<FiltrationResults>
| Prop | Type | Default | Description |
|---|
aria-label | string | – | Names the applied-filters chip group for assistive tech, e.g. "Applied filters". |
<FiltrationPanel>
| Prop | Type | Default | Description |
|---|
deferPointerDownOutside | boolean | – | When true, a 'pointerdown' event outside of the layered element will
wait for the interaction's click event before dispatching, allowing
third-party code to stop propagation of later events and cancel dismissal. |
onEscapeKeyDown | (event: KeyboardEvent) => void | – | Event handler called when the escape key is down.
Can be prevented. |
onPointerDownOutside | (event: PointerDownOutsideEvent) => void | – | Event handler called when the a pointerdown event happens outside of the DismissableLayer.
Can be prevented. |
onFocusOutside | (event: FocusOutsideEvent) => void | – | Event handler called when the focus moves outside of the DismissableLayer.
Can be prevented. |
onInteractOutside | (event: PointerDownOutsideEvent | FocusOutsideEvent) => void | – | Event handler called when an interaction happens outside the DismissableLayer.
Specifically, when a pointerdown event happens outside or focus moves outside of it.
Can be prevented. |
forceMount | true | – | Used to force mounting when more control is needed. Useful when
controlling animation with React animation libraries. |
onOpenAutoFocus | (event: Event) => void | – | Event handler called when auto-focusing on open.
Can be prevented. |
onCloseAutoFocus | (event: Event) => void | – | Event handler called when auto-focusing on close.
Can be prevented. |
side | "top" | "right" | "bottom" | "left" | – | |
sideOffset | number | – | |
align | "center" | "start" | "end" | – | |
alignOffset | number | – | |
arrowPadding | number | – | |
avoidCollisions | boolean | – | |
collisionBoundary | Element | Element[] | – | |
collisionPadding | number | Partial<Record<"top" | "right" | "bottom" | "left", number>> | – | |
sticky | "always" | "partial" | – | |
hideWhenDetached | boolean | – | |
updatePositionStrategy | "always" | "optimized" | – | |
<FiltrationCheckboxFilter>
| Prop | Type | Default | Description |
|---|
optionsrequired | FiltrationCheckboxOption[] | – | |
value | string[] | – | Controlled selected values. |
defaultValue | string[] | – | Uncontrolled initial selected values. |
onValueChange | (next: string[]) => void | – | |
searchable | boolean | – | Show a search field that filters options by label. |
searchPlaceholder | string | – | |
searchLabel | string | – | Accessible label for the search field (it has no visible label). |
collapseAfter | number | – | Collapse to the first N options behind a "Show more" toggle. |
showMoreLabel | (remaining: number) => ReactNode | – | Maps the hidden-count → the expand button label. Default Show {n} more. |
showLessLabel | react.ReactNode | – | |
aria-label | string | – | Defines a string value that labels the current element. |
aria-labelledby | string | – | Identifies the element (or elements) that labels the current element. |
className | string | – | |
<FiltrationOptionList>
| Prop | Type | Default | Description |
|---|
name | string | – | |
form | string | – | |
required | boolean | – | |
disabled | boolean | – | |
dir | Direction | – | |
orientation | "vertical" | "horizontal" | – | |
loop | boolean | – | |
defaultValue | string | – | |
value | string | – | |
onValueChange | (value: string) => void | – | |
<FiltrationOption>
| Prop | Type | Default | Description |
|---|
childrenrequired | react.ReactNode | – | |
asChild | boolean | – | |
checked | boolean | – | |
required | boolean | – | |
valuerequired | string | – | |
<FiltrationFooter>
| Prop | Type | Default | Description |
|---|
applyLabel | react.ReactNode | – | |
clearLabel | react.ReactNode | – | |
appliedCount | number | – | Appended to the apply label as (n). |
onApply | () => void | – | |
onClear | () => void | – | |
closeOnApply | boolean | – | Close the overlay when Apply is pressed (overlay only). Default true. |
Accessibility
Each section is a role="group" named by its heading, and the overlay trigger exposes aria-expanded and aria-controls. Filters inside are real checkboxes and inputs with labels.
Apply and Clear are buttons, and the results count is text so screen readers can read how many matches remain.