Components

Filter

A dropdown component for filtering item lists. Presents a searchable multi-select list of options with a badge showing the number of active selections.

Replacing soon

GitHub

Anatomy

import {Filter} from '@staffbase/design';

<Filter />;

Examples

Empty state

When options is empty or the search query matches nothing, the component shows the emptyResultText message.

With external search

For server-side filtering, use onSearchChange, clearSearch, and externalSearchQuery together. The component will call onSearchChange as the user types and delegate filtering to you.

Anatomy

import {Filter} from '@staffbase/design';

<Filter
  options={serverOptions}
  triggerLabel="Category"
  searchInputPlaceholder="Search"
  emptyResultText="No results"
  clearButtonText="Clear all"
  applyButtonText="Apply"
  badgeA11yDescription="Number of selected filters"
  externalSearchQuery={query}
  onSearchChange={(value, localOptions) => fetchOptions(value)}
  clearSearch={(localOptions) => clearOptions()}
  onApply={handleApply}
/>;

API reference

Name	Type	Description
`options`	`Option[]`	Array of filter options. Each option has `id` (string \| number, required), `label` (string, required), `selected` (boolean, required), and optional `key`, `index`, `props`.
`triggerLabel`	`string`	Label for the trigger button.
`badgeA11yDescription`	`string`	Accessible description for the badge showing the count of selected options.
`searchInputPlaceholder`	`string`	Placeholder text for the internal search input.
`emptyResultText`	`string`	Message displayed when no options match the search query or the list is empty.
`clearButtonText`	`string`	Label for the clear all button.
`applyButtonText`	`string`	Label for the apply button.
`onApply`	`(options: Option[]) => void`	Called with the full options array (including updated `selected` values) when the apply button is clicked.
`triggerIcon`	`ReactElement`	Icon rendered inside the trigger button.
`loading`	`boolean`	When `true`, shows a loading spinner in place of the options list.
`placement`	`Placement`	Floating-UI placement for the dropdown. Default:`'bottom-start'`
`onSearchChange`	`(value: string, localOptions: Option[]) => void`	Enables external (server-side) search. Called as the user types. Must be used with `clearSearch` and `externalSearchQuery`.
`clearSearch`	`(localOptions: Option[]) => void`	Called when the search is cleared in external search mode.
`externalSearchQuery`	`string`	The current external search query value.
`containerClassname`	`string`	CSS class applied to the floating dropdown container.
`triggerClassname`	`string`	CSS class applied to the trigger button element.

Always provide badgeA11yDescription so screen readers can announce the number of active filters.
Keep triggerLabel short and descriptive — it should name the category being filtered, not describe the action.
Use loading when fetching options asynchronously to prevent interaction with a stale list.
For large datasets, use external search (onSearchChange, clearSearch, externalSearchQuery) instead of relying on client-side filtering.
Apply selections only on the “Apply” button click — do not trigger filtering on every checkbox toggle.