Filters
⋯
Filters supplies layout and common controls for the Filters bar, dropdown editor, and slideout anatomy. It does not define filter fields, operators, query syntax, or data fetching.
Import Filters from @nesra/ui/filters or @nesra/ui. Compose its parts with Input, Select, DatePicker, Button, or other controls.
import { Filters } from "@nesra/ui/filters";import { Input } from "@nesra/ui/input";
export function OrderFilters() { return ( <Filters.Bar> <Filters.Content> <Input aria-label="Search orders" placeholder="Search orders" /> </Filters.Content> </Filters.Bar> );}Composition
Section titled “Composition”Filters.Bar├─ Filters.Content│ └─ application controls or Filters.List│ └─ Filters.Row│ ├─ Filters.Fields (field, operator, value)│ └─ Filters.Remove (optional)└─ Filters.Actions (optional)Filters.Bar wraps on narrow screens. Filters.Fields places its third child below the first two until the sm breakpoint.
Examples
Section titled “Examples”Simple bar
Section titled “Simple bar”This example follows the Figma bar’s search/select/action structure. The search and status values are controlled by the page.
import { useState } from "react";import { Button } from "@nesra/ui/button";import { Filters } from "@nesra/ui/filters";import { Input } from "@nesra/ui/input";import { Select } from "@nesra/ui/select";
export function FiltersSimpleExample() { const [query, setQuery] = useState(""); const [status, setStatus] = useState("");
return ( <Filters.Bar> <Filters.Content> <Input aria-label="Search orders" className="w-full sm:w-60" onChange={(event) => setQuery(event.target.value)} placeholder="Search orders" value={query} /> <Select aria-label="Order status" className="w-full sm:w-40" items={{ paid: "Paid", pending: "Pending" }} onValueChange={(value) => setStatus(value ?? "")} placeholder="Status" value={status} /> </Filters.Content> <Filters.Actions> <Button onClick={() => { setQuery(""); setStatus(""); }} size="sm" variant="outline" > Clear all </Button> </Filters.Actions> </Filters.Bar> );}Tabs and search
Section titled “Tabs and search”The page keeps the desktop Tabs and mobile Select on the same controlled view value. The search
field and status filter are also application state. Customize search toggles the search control.
import { useState } from "react";import { Button } from "@nesra/ui/button";import { Filters } from "@nesra/ui/filters";import { Input } from "@nesra/ui/input";import { Popover } from "@nesra/ui/popover";import { Select } from "@nesra/ui/select";import { Tabs } from "@nesra/ui/tabs";
export function FiltersTabsSearchExample() { const [view, setView] = useState("all"); const [query, setQuery] = useState(""); const [status, setStatus] = useState(""); const [showSearch, setShowSearch] = useState(true);
return ( <Tabs.Root className="w-full" onValueChange={(value) => { if (typeof value === "string") setView(value); }} value={view} variant="pill" > <Filters.Bar className="items-center"> <Filters.Content className="basis-full items-center sm:basis-0"> <Select aria-label="Order view" className="w-full sm:hidden" items={{ all: "View all", active: "Active", history: "History" }} onValueChange={(value) => { if (value) setView(value); }} value={view} /> <Tabs.List aria-label="Order views" className="w-auto"> <Tabs.Trigger value="all">View all</Tabs.Trigger> <Tabs.Trigger value="active">Active</Tabs.Trigger> <Tabs.Trigger value="history">History</Tabs.Trigger> </Tabs.List> {showSearch && ( <Input aria-label="Search orders" className="w-full min-w-40 flex-1 sm:ml-auto sm:w-auto" onChange={(event) => setQuery(event.target.value)} placeholder="Search" value={query} /> )} </Filters.Content> <Filters.Actions> <Popover> <Popover.Trigger render={<Filters.Trigger />}>Filters</Popover.Trigger> <Popover.Content> <Popover.Title>Filter orders</Popover.Title> <Select className="mt-nesra-spacing-lg w-56" items={{ paid: "Paid", pending: "Pending" }} label="Status" onValueChange={(value) => setStatus(value ?? "")} placeholder="View all" value={status} /> </Popover.Content> </Popover> <Button aria-pressed={showSearch} onClick={() => setShowSearch((current) => !current)} size="sm" variant="outline" > Customize search </Button> </Filters.Actions> </Filters.Bar> <div className="mt-nesra-spacing-lg type-nesra-body-small-regular text-nesra-text-support"> <Tabs.Panel value="all"> All orders matching “{query || "any search"}” · {status || "any status"} </Tabs.Panel> <Tabs.Panel value="active"> Active orders matching “{query || "any search"}” · {status || "any status"} </Tabs.Panel> <Tabs.Panel value="history"> Order history matching “{query || "any search"}” · {status || "any status"} </Tabs.Panel> </div> </Tabs.Root> );}Dropdowns and date range
Section titled “Dropdowns and date range”The compact date trigger opens the calendar presentation of DatePicker in a Popover. Completing
a range or choosing a preset updates the trigger and closes the popup. The page owns sort order,
status, and the committed range.
import { useState } from "react";import { Button } from "@nesra/ui/button";import { DatePicker, type DateRange } from "@nesra/ui/date-picker";import { Filters } from "@nesra/ui/filters";import { Popover } from "@nesra/ui/popover";import { Select } from "@nesra/ui/select";import { CalendarDays } from "lucide-react";
function formatDate(value: string) { const [year, month, day] = value.split("-").map(Number); return new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric", timeZone: "UTC", }).format(new Date(Date.UTC(year!, month! - 1, day)));}
function dateRangeLabel(period: DateRange | null) { if (!period) return "Select dates"; return `${formatDate(period.start)} – ${formatDate(period.end)}`;}
export function FiltersDropdownsDateExample() { const [sort, setSort] = useState("descending"); const [status, setStatus] = useState(""); const [period, setPeriod] = useState<DateRange | null>(null); const [datePickerOpen, setDatePickerOpen] = useState(false);
return ( <Filters.Bar className="items-end"> <Filters.Content className="items-end"> <Select className="w-full sm:w-40" items={{ descending: "Descending", ascending: "Ascending" }} label="Sort by" onValueChange={(value) => setSort(value ?? "descending")} value={sort} /> <Select className="w-full sm:w-40" items={{ paid: "Paid", pending: "Pending" }} label="Status" onValueChange={(value) => setStatus(value ?? "")} placeholder="View all" value={status} /> <div className="w-full sm:w-auto"> <p className="mb-nesra-spacing-sm type-nesra-body-small-medium text-nesra-text-headline"> Date range </p> <Popover open={datePickerOpen} onOpenChange={setDatePickerOpen}> <Popover.Trigger render={ <Button aria-label="Choose date range" className="w-full sm:min-w-64" size="sm" startIcon={<CalendarDays size={16} />} variant="outline" /> } > {dateRangeLabel(period)} </Popover.Trigger> <Popover.Content align="start" className="w-[min(836px,calc(100vw-24px))] p-nesra-padding-xl" > <Popover.Title className="sr-only">Choose date range</Popover.Title> <DatePicker label="Date range" mode="range" onValueChange={(value) => { setPeriod(value); setDatePickerOpen(false); }} presentation="calendar" timeZone="Asia/Jakarta" value={period} /> </Popover.Content> </Popover> </div> </Filters.Content> <Filters.Actions className="pb-nesra-spacing-xs"> <Button onClick={() => { setSort("descending"); setStatus(""); setPeriod(null); }} size="sm" variant="outline" > Clear all </Button> </Filters.Actions> </Filters.Bar> );}Active filters inline
Section titled “Active filters inline”Rows can stay in the bar rather than opening an editor. Add, remove, clear, and apply remain page actions.
import { useState } from "react";import { Button } from "@nesra/ui/button";import { Filters } from "@nesra/ui/filters";import { Input } from "@nesra/ui/input";import { Select } from "@nesra/ui/select";
type FilterRow = { id: number; field: string; operator: string; value: string };
export function FiltersInlineExample() { const [rows, setRows] = useState<FilterRow[]>([ { id: 1, field: "status", operator: "equals", value: "Active" }, { id: 2, field: "email", operator: "contains", value: "gmail" }, ]); const [nextId, setNextId] = useState(3); const [appliedCount, setAppliedCount] = useState(2);
function updateRow(id: number, patch: Partial<FilterRow>) { setRows((current) => current.map((row) => (row.id === id ? { ...row, ...patch } : row))); }
return ( <Filters.Bar> <Filters.Content className="min-w-[min(560px,100%)]"> <Filters.List className="w-full max-w-[560px]"> {rows.map((row) => ( <Filters.Row key={row.id}> <Filters.Fields> <Select aria-label={`Filter field ${row.id}`} items={{ status: "Status", email: "Email", team: "Team" }} onValueChange={(field) => updateRow(row.id, { field: field ?? "" })} placeholder="Filter" value={row.field} /> <Select aria-label={`Filter operator ${row.id}`} items={{ equals: "Equals", contains: "Contains" }} onValueChange={(operator) => updateRow(row.id, { operator: operator ?? "" })} value={row.operator} /> <Input aria-label={`Filter value ${row.id}`} onChange={(event) => updateRow(row.id, { value: event.target.value })} placeholder="Enter a value" value={row.value} /> </Filters.Fields> <Filters.Remove aria-label={`Remove filter ${row.id}`} onClick={() => setRows((current) => current.filter((item) => item.id !== row.id))} /> </Filters.Row> ))} </Filters.List> </Filters.Content> <Filters.Actions className="ml-auto"> <Button onClick={() => { setRows((current) => [ ...current, { id: nextId, field: "", operator: "equals", value: "" }, ]); setNextId((current) => current + 1); }} size="sm" variant="outline" > Add filter </Button> <Button onClick={() => { setRows([]); setAppliedCount(0); }} size="sm" variant="outline" > Clear all </Button> <Button onClick={() => setAppliedCount(rows.filter((row) => row.field && row.value).length)} size="sm" > Apply filters {appliedCount > 0 ? `(${appliedCount})` : ""} </Button> </Filters.Actions> </Filters.Bar> );}Advanced editor
Section titled “Advanced editor”The Figma advanced pattern has a field, operator, searchable multi-value control, and remove action
per row. Here, Popover handles the anchored editor and focus behavior. The example keeps draft
rows separate from applied rows; the application decides which drafts are valid.
import { useState } from "react";import { Button } from "@nesra/ui/button";import { Filters } from "@nesra/ui/filters";import { MultiSelect, type MultiSelectItem } from "@nesra/ui/multi-select";import { Popover } from "@nesra/ui/popover";import { Select } from "@nesra/ui/select";
const teams: MultiSelectItem[] = [ { value: "engineering", label: "Engineering", supportingText: "12 users", count: 3 }, { value: "design", label: "Design", supportingText: "10 users", count: 3 }, { value: "product", label: "Product", supportingText: "6 users", count: 3 }, { value: "marketing", label: "Marketing", supportingText: "8 users", count: 3 },];
type FilterRow = { id: number; field: string; operator: string; values: string[] };const emptyRow = (id: number): FilterRow => ({ id, field: "team", operator: "includes-any", values: [],});
export function FiltersAdvancedExample() { const [rows, setRows] = useState<FilterRow[]>([emptyRow(1)]); const [nextId, setNextId] = useState(2); const [applied, setApplied] = useState<FilterRow[]>([]);
function updateRow(id: number, patch: Partial<FilterRow>) { setRows((current) => current.map((row) => (row.id === id ? { ...row, ...patch } : row))); }
return ( <div> <Popover> <Popover.Trigger render={<Filters.Trigger count={applied.length} />}> Filters </Popover.Trigger> <Popover.Content align="start" className="w-[min(624px,calc(100vw-24px))] p-0"> <Popover.Title className="sr-only">Edit filters</Popover.Title> <Filters.List className="px-nesra-spacing-xl"> {rows.map((row) => ( <Filters.Row key={row.id}> <Filters.Fields> <Select aria-label={`Filter field ${row.id}`} items={{ team: "Team" }} onValueChange={(field) => updateRow(row.id, { field: field ?? "" })} placeholder="Select filter" value={row.field} /> <Select aria-label={`Filter operator ${row.id}`} items={{ "includes-any": "Includes any" }} onValueChange={(operator) => updateRow(row.id, { operator: operator ?? "" })} value={row.operator} /> <MultiSelect aria-label={`Filter value ${row.id}`} items={teams} onValueChange={(values) => updateRow(row.id, { values })} placeholder="Select teams" value={row.values} /> </Filters.Fields> <Filters.Remove aria-label={`Remove filter ${row.id}`} onClick={() => setRows((current) => current.filter((item) => item.id !== row.id))} /> </Filters.Row> ))} </Filters.List> <div className="flex flex-wrap items-center justify-between gap-nesra-spacing-lg border-t border-nesra-stroke-border p-nesra-spacing-xl"> <Button onClick={() => { setRows((current) => [...current, emptyRow(nextId)]); setNextId((current) => current + 1); }} size="sm" variant="outline" > Add filter </Button> <Filters.Actions> <Button onClick={() => setRows([])} size="sm" variant="outline"> Clear all </Button> <Popover.Close onClick={() => setApplied(rows.filter((row) => row.field && row.values.length > 0))} render={<Button size="sm" />} > Apply filters </Popover.Close> </Filters.Actions> </div> </Popover.Content> </Popover> <p className="mt-nesra-spacing-xl type-nesra-body-small-regular text-nesra-text-support"> {applied.length} applied filters </p> </div> );}Slideout editor
Section titled “Slideout editor”The same row layout and MultiSelect value editor work inside Sheet.Content. Sheet.Header and
Sheet.Footer provide the title and actions. Sheet manages focus, dismissal, and the backdrop.
import { useState } from "react";import { Button } from "@nesra/ui/button";import { Filters } from "@nesra/ui/filters";import { MultiSelect, type MultiSelectItem } from "@nesra/ui/multi-select";import { Select } from "@nesra/ui/select";import { Sheet } from "@nesra/ui/sheet";
const usersByTeam: Record<string, number> = { engineering: 12, design: 10, product: 6, marketing: 8, "customer-success": 4,};
const teams: MultiSelectItem[] = [ { value: "engineering", label: "Engineering", supportingText: "12 users", count: 3 }, { value: "design", label: "Design", supportingText: "10 users", count: 3 }, { value: "product", label: "Product", supportingText: "6 users", count: 3 }, { value: "marketing", label: "Marketing", supportingText: "8 users", count: 3 }, { value: "customer-success", label: "Customer Success", supportingText: "4 users", count: 3, },];
type FilterRow = { id: number; field: string; operator: string; values: string[] };const emptyRow = (id: number): FilterRow => ({ id, field: "team", operator: "includes-any", values: [],});
export function FiltersSlideoutExample() { const [rows, setRows] = useState<FilterRow[]>([ { ...emptyRow(1), values: ["engineering", "customer-success"] }, ]); const [nextId, setNextId] = useState(2); const [applied, setApplied] = useState<FilterRow[]>([]);
function updateRow(id: number, patch: Partial<FilterRow>) { setRows((current) => current.map((row) => (row.id === id ? { ...row, ...patch } : row))); }
return ( <Sheet> <Sheet.Trigger render={<Filters.Trigger count={applied.length} showChevron={false} />}> Edit filters </Sheet.Trigger> <Sheet.Content> <Sheet.Header className="flex-row items-start border-b-0"> <div className="min-w-0 flex-1"> <Sheet.Title>Filters</Sheet.Title> <Sheet.Description>Add filters to narrow down results.</Sheet.Description> </div> <Sheet.Close /> </Sheet.Header> <div className="flex-1 px-nesra-spacing-xl sm:px-nesra-spacing-3xl"> <Filters.List> {rows.map((row) => ( <Filters.Row key={row.id}> <Filters.Fields> <Select aria-label={`Filter field ${row.id}`} items={{ team: "Team" }} onValueChange={(field) => updateRow(row.id, { field: field ?? "" })} placeholder="Select filter" value={row.field} /> <Select aria-label={`Filter operator ${row.id}`} items={{ "includes-any": "Includes any" }} onValueChange={(operator) => updateRow(row.id, { operator: operator ?? "" })} placeholder="Includes any" value={row.operator} /> <MultiSelect aria-label={`Filter value ${row.id}`} items={teams} onValueChange={(values) => updateRow(row.id, { values })} placeholder="Select teams" summary={(selected) => `${selected.reduce((total, item) => total + (usersByTeam[item.value] ?? 0), 0)} users` } value={row.values} /> </Filters.Fields> <Filters.Remove aria-label={`Remove filter ${row.id}`} onClick={() => setRows((current) => current.filter((item) => item.id !== row.id))} /> </Filters.Row> ))} </Filters.List> <Button className="mt-nesra-spacing-lg" onClick={() => { setRows((current) => [...current, emptyRow(nextId)]); setNextId((current) => current + 1); }} size="sm" variant="outline" > Add filter </Button> </div> <Sheet.Footer> <Button onClick={() => setRows([])} size="sm" variant="outline"> Clear all </Button> <Sheet.Close onClick={() => setApplied(rows.filter((row) => row.field && row.values.length > 0))} render={<Button size="sm" />} > Apply filters </Sheet.Close> </Sheet.Footer> </Sheet.Content> </Sheet> );}Filters.Trigger can be passed to either Popover.Trigger or Sheet.Trigger through Base UI’s render prop.
Light and Dark
Section titled “Light and Dark”The filter parts use the Figma Filters roles in both modes. Filters.List separates rows with
--nesra-stroke-border. The Filters.Trigger count uses --nesra-surface-card-bg-neutral with a
--nesra-stroke-border border. Keyboard focus on Filters.Trigger shows
shadow-nesra-focus-ring-offset, the Figma Focused state: a 2px foundation-bg-neutral gap and a
4px focus ring. The slideout example inherits the Sheet backdrop: --nesra-foundation-bg-overlay
at 70% with a 16px blur.
The Figma Filters sets are still marked as changed and unpublished. Hover and default fills for the
trigger come from Button.
Accessibility
Section titled “Accessibility”Filters.Bar groups Filters.Content and Filters.Actions. Filters.List stacks Filters.Row elements. Each row uses Filters.Fields for three application-supplied controls and can include Filters.Remove. Give every control a distinct accessible name, such as “Filter field 1” and “Filter value 1”, and give Filters.Remove a row-specific aria-label. The layout parts do not add keyboard behavior or form semantics; the composed controls provide those. Popover and Sheet retain their own disclosure, focus, and dismissal behavior.
MultiSelect supplies search, multiple-selection semantics, and bulk actions for the team value
editors. The application still owns which value editor matches each filter field and how selected
values become a query.
API reference
Section titled “API reference”Filters.Bar
Section titled “Filters.Bar”Wraps Filters.Content and Filters.Actions in a responsive flex container. It accepts native
div props and className. Its ref points to the root div.
Filters.Content
Section titled “Filters.Content”Grows around application-supplied controls and wraps them when necessary. It accepts native div
props and className. Its ref points to the content div.
Filters.Actions
Section titled “Filters.Actions”Groups application-supplied action buttons in a wrapping flex container. It accepts native div
props and className. Its ref points to the actions div.
Filters.List
Section titled “Filters.List”Stacks filter rows and renders a divider between adjacent children. It accepts native div props
and className. Its ref points to the list div.
Filters.Row
Section titled “Filters.Row”Aligns one Filters.Fields group with an optional Filters.Remove. It accepts native div props
and className. Its ref points to the row div.
Filters.Fields
Section titled “Filters.Fields”Lays out field, operator, and value controls in a responsive grid. It accepts native div props
and className. Its ref points to the fields div.
Filters.Trigger
Section titled “Filters.Trigger”Renders a Button for composition with Popover.Trigger or Sheet.Trigger through the render
prop.
| Prop | Type | Default | Effect |
|---|---|---|---|
children |
ReactNode |
"Filters" |
Sets the visible trigger label. |
count |
number |
— | Renders an applied-filter count when supplied. |
showChevron |
boolean |
true |
Shows or hides the disclosure chevron. |
size |
"sm" | "md" | "lg" | "icon-sm" | "icon-md" | "icon-lg" |
"sm" |
Sets the button dimensions. |
variant |
"primary" | "outline" | "ghost" | "destructive" | "link" |
"outline" |
Sets the button appearance. |
Filters.Trigger accepts the other Button props except startIcon and endIcon, including
disabled, loading, onClick, render, and className. Its ref points to the button element.
Filters.Remove
Section titled “Filters.Remove”Renders an icon-only Button. The application supplies the remove handler and a row-specific
accessible name.
| Prop | Type | Default | Effect |
|---|---|---|---|
aria-label |
string |
Required | Names the row-specific remove action. |
size |
"sm" | "md" | "lg" | "icon-sm" | "icon-md" | "icon-lg" |
"icon-sm" |
Sets the button dimensions. |
variant |
"primary" | "outline" | "ghost" | "destructive" | "link" |
"ghost" |
Sets the button appearance. |
Filters.Remove accepts the other Button props except children, startIcon, and endIcon,
including disabled, loading, onClick, render, and className. Its ref points to the button
element.