Filter Dropdown

Category Menu

A compact category selector with icons. Click a category to drill into its options.

<FilterDropdown.Root>
  <FilterDropdown.Trigger asChild>
    <Button.Root variant="neutral" mode="stroke">
      <Button.Icon as={RiFilterLine} />
      Filters
    </Button.Root>
  </FilterDropdown.Trigger>
  <FilterDropdown.Content className="w-[224px]">
    <FilterDropdown.CategoryList>
      <FilterDropdown.CategoryItem icon={RiPuzzle2Line}>Types</FilterDropdown.CategoryItem>
      <FilterDropdown.CategoryItem icon={RiEyeLine}>Visibility</FilterDropdown.CategoryItem>
    </FilterDropdown.CategoryList>
  </FilterDropdown.Content>
</FilterDropdown.Root>

Text Options

Multi-select filter with plain text options, select all, and apply button.

<FilterDropdown.Content>
  <FilterDropdown.Header onBack={handleBack} onReset={reset} />
  <FilterDropdown.SelectAll checked={allChecked} onCheckedChange={selectAll} />
  <FilterDropdown.Group>
    <FilterDropdown.Item checked={selected.has('Grant')} onCheckedChange={() => toggle('Grant')}>Grant</FilterDropdown.Item>
  </FilterDropdown.Group>
  <FilterDropdown.Apply onClick={handleApply} />
</FilterDropdown.Content>

Badge Options

Filter options rendered as badges (e.g., deadline status with colored indicators).

<FilterDropdown.Item checked={true} onCheckedChange={handleChange}>
  <Badge.Root variant="light" color="green" size="small">Open</Badge.Root>
</FilterDropdown.Item>

Status Badge Options

Filter options rendered as status badges for publication status filtering.

<FilterDropdown.Item checked={true} onCheckedChange={handleChange}>
  <StatusBadge.Root>Waiting for review</StatusBadge.Root>
</FilterDropdown.Item>

With Search

Filter with a search input for large option lists (e.g., people/users).

<FilterDropdown.Content>
  <FilterDropdown.Header onBack={handleBack} onReset={reset} />
  <FilterDropdown.Search value={search} onChange={(e) => setSearch(e.target.value)} />
  <FilterDropdown.SelectAll checked={allChecked} onCheckedChange={selectAll} />
  <FilterDropdown.Group>
    {filtered.map((person) => (
      <FilterDropdown.Item key={person} checked={selected.has(person)} onCheckedChange={() => toggle(person)}>
        <Avatar /> {person}
      </FilterDropdown.Item>
    ))}
  </FilterDropdown.Group>
  <FilterDropdown.Apply onClick={handleApply} />
</FilterDropdown.Content>

Two-Level Navigation

Complete example with category menu that drills into option panels. Navigation state is managed by the consumer.

// Consumer manages view state
const [view, setView] = useState('categories');

<FilterDropdown.Content className={view === 'categories' ? 'w-[224px]' : undefined}>
  {view === 'categories' && (
    <FilterDropdown.CategoryList>
      <FilterDropdown.CategoryItem icon={RiPuzzle2Line} onClick={() => setView('types')}>Types</FilterDropdown.CategoryItem>
    </FilterDropdown.CategoryList>
  )}
  {view === 'types' && (
    <>
      <FilterDropdown.Header onBack={() => setView('categories')} onReset={reset} />
      <FilterDropdown.SelectAll checked={allChecked} onCheckedChange={selectAll} />
      <FilterDropdown.Group>
        <FilterDropdown.Item checked={true} onCheckedChange={handleChange}>Grant</FilterDropdown.Item>
      </FilterDropdown.Group>
      <FilterDropdown.Apply onClick={handleApply} />
    </>
  )}
</FilterDropdown.Content>

Flat Filter

Single-level filter without category navigation — just options, select all, and apply.

<FilterDropdown.Content>
  <FilterDropdown.Header onReset={reset} />
  <FilterDropdown.SelectAll checked={allChecked} onCheckedChange={selectAll} />
  <FilterDropdown.Group>
    <FilterDropdown.Item checked={true} onCheckedChange={handleChange}>Visible for members</FilterDropdown.Item>
    <FilterDropdown.Item checked={false} onCheckedChange={handleChange}>Hidden from members</FilterDropdown.Item>
  </FilterDropdown.Group>
  <FilterDropdown.Apply onClick={handleApply} />
</FilterDropdown.Content>

Composed (Two-Level)

The Composed shorthand renders a full two-level filter dropdown from a config array. When 2+ filters are provided, a category menu is shown first.

<FilterDropdown.Composed
  filters={[
    { key: 'types', label: 'Types', icon: RiPuzzle2Line, options: [{ value: 'grant', label: 'Grant' }, { value: 'loan', label: 'Loan' }] },
    { key: 'visibility', label: 'Visibility', icon: RiEyeLine, options: [{ value: 'visible', label: 'Visible' }, { value: 'hidden', label: 'Hidden' }] },
  ]}
  selected={{ types: [], visibility: [] }}
  onSelectedChange={(key, values) => setSelected(prev => ({ ...prev, [key]: values }))}
  onApply={(sel) => console.log(sel)}
>
  <Button.Root>Filters</Button.Root>
</FilterDropdown.Composed>

Composed (Flat)

When a single filter is provided, the Composed variant skips the category menu and renders options directly.

<FilterDropdown.Composed
  filters={[
    { key: 'visibility', label: 'Visibility', options: [{ value: 'visible', label: 'Visible' }, { value: 'hidden', label: 'Hidden' }] },
  ]}
  selected={{ visibility: [] }}
  onSelectedChange={(key, values) => setSelected(prev => ({ ...prev, [key]: values }))}
  onApply={(sel) => console.log(sel)}
>
  <Button.Root>Visibility</Button.Root>
</FilterDropdown.Composed>

Composed with Search

Composed variant with searchable enabled for large option lists.

<FilterDropdown.Composed
  filters={[
    { key: 'people', label: 'Created by', icon: RiUserLine, searchable: true, searchPlaceholder: 'Search people...', options: people.map(p => ({ value: p, label: p })) },
  ]}
  selected={{ people: [] }}
  onSelectedChange={(key, values) => setSelected(prev => ({ ...prev, [key]: values }))}
  onApply={(sel) => console.log(sel)}
>
  <Button.Root>Created by</Button.Root>
</FilterDropdown.Composed>

Composed with Badges

Composed variant where option labels are ReactNode (Badge components) instead of plain strings.

<FilterDropdown.Composed
  filters={[{
    key: 'deadline',
    label: 'Deadline status',
    options: [
      { value: 'Open', label: <Badge.Root variant="light" color="green" size="small">Open</Badge.Root> },
      { value: 'Closed', label: <Badge.Root variant="light" color="red" size="small">Closed</Badge.Root> },
    ],
  }]}
  selected={{ deadline: [] }}
  onSelectedChange={(key, values) => setSelected(prev => ({ ...prev, [key]: values }))}
  onApply={(sel) => console.log(sel)}
>
  <Button.Root>Deadline status</Button.Root>
</FilterDropdown.Composed>

Composed with Remote Search

Composed variant with server-side search and infinite scroll. The remote.onFetch callback is called on mount, on search input change (debounced), and when the user scrolls near the bottom. Options are passed as empty initially — the component fetches them lazily. A loading spinner shows during initial fetch, and a smaller spinner appears at the bottom of the list when loading more pages.

const fetchProviders = async ({ query, page }) => {
  const res = await fetch(`/api/providers?q=${query}&page=${page}&limit=20`);
  const data = await res.json();
  return {
    options: data.items.map(p => ({ value: p.id, label: p.name })),
    hasMore: data.currentPage < data.lastPage,
  };
};

<FilterDropdown.Composed
  filters={[{
    key: 'providers',
    label: 'Providers',
    icon: RiUserLine,
    searchable: true,
    searchPlaceholder: 'Search providers...',
    options: [],
    remote: { onFetch: fetchProviders, debounceMs: 300 },
  }]}
  selected={{ providers: [] }}
  onSelectedChange={(key, values) => setSelected(prev => ({ ...prev, [key]: values }))}
  onApply={(sel) => console.log(sel)}
>
  <Button.Root>Providers</Button.Root>
</FilterDropdown.Composed>

Two-Level with Remote Category

Multi-category filter where one category uses static local options and another uses remote server-side search with infinite scroll. Demonstrates mixing static and remote filters in the same dropdown.

<FilterDropdown.Composed
  filters={[
    {
      key: 'types',
      label: 'Types',
      icon: RiPuzzle2Line,
      searchable: true,
      options: types.map(t => ({ value: t, label: t })),
    },
    {
      key: 'providers',
      label: 'Providers',
      icon: RiUserLine,
      searchable: true,
      searchPlaceholder: 'Search providers...',
      options: [],
      remote: { onFetch: fetchProviders, debounceMs: 300 },
    },
  ]}
  selected={selected}
  onSelectedChange={(key, values) => setSelected(prev => ({ ...prev, [key]: values }))}
  onApply={(sel) => console.log(sel)}
>
  <Button.Root>Filters</Button.Root>
</FilterDropdown.Composed>

FilterDropdown.Root

The root container. Wraps Radix Popover.Root.

FilterDropdown.Trigger

The element that opens the filter dropdown.

FilterDropdown.Content

The dropdown content panel with border, shadow, and animations.

FilterDropdown.Header

Navigation header with Back and Reset filter buttons.

FilterDropdown.Search

A search input with magnifying glass icon for filtering options.

FilterDropdown.SelectAll

Checkbox with 'Select all' label and a divider below. Supports indeterminate state.

FilterDropdown.Group

Scrollable container for filter items with a custom scrollbar. Supports infinite scroll via onScrollEnd.

FilterDropdown.Item

A selectable filter option with a checkbox. Accepts children for flexible content (text, badges, avatars).

FilterDropdown.ItemIcon

Polymorphic icon for use inside Item children.

FilterDropdown.CategoryList

Container for category items in the category menu view.

FilterDropdown.CategoryItem

A non-checkbox item with an icon for category navigation.

FilterDropdown.Apply

Full-width apply button at the bottom of the filter panel.

FilterDropdown.Composed

A composed shorthand that renders a complete filter dropdown from a config array. Automatically handles two-level category navigation (2+ filters) or flat single-level (1 filter). Manages internal view state, search, select all, and reset.

FilterConfig

Configuration object for each filter group passed to FilterDropdown.Composed.

RemoteFetchResult

Return type for the remote.onFetch callback.