Filter menu

A filter button whose menu lists the fields you can filter by, then each field's values. Start typing and the same menu becomes a search across every field and value, like a command menu.

Features

• Two levels: pick a field such as Status, then tick any number of its values. Each field shows how many of its values are on.
• Typing turns the menu into a search, grouped by field, with the matching letters in bold. Inside a field, the search stays within it.
• Or, with search="button", a Search filters button takes the place of the search box, and the menu slides over to its search state when it's used.
• Escape steps back: first it clears the search, then it leaves the field, and only then does it close the menu.
• Views slide forward and back, and the popup's height follows its content. Under reduced motion, views swap in place.

Installation

It installs the Button component and the motion package too.

Usage

import { useState } from "react"
 
import {
  FilterMenu,
  type FilterField,
  type FilterValue,
} from "@/components/ui/filter-menu"
 
const fields: FilterField[] = [
  {
    id: "status",
    label: "Status",
    options: [
      { value: "todo", label: "Todo" },
      { value: "done", label: "Done" },
    ],
  },
  {
    id: "priority",
    label: "Priority",
    options: [
      { value: "urgent", label: "Urgent" },
      { value: "low", label: "Low" },
    ],
  },
]
 
export function IssueFilters() {
  const [filters, setFilters] = useState<FilterValue>({})
  return (
    <FilterMenu fields={fields} value={filters} onValueChange={setFilters} />
  )
}

The menu only picks filters. value holds the chosen values keyed by field id, such as { status: ["todo"] }, and showing the applied filters is up to your app.

type FilterField = {
  id: string
  label: string
  icon?: React.ReactNode
  options: { value: string; label: string; icon?: React.ReactNode }[]
}
 
type FilterValue = Record<string, string[]>

Anatomy

Guidelines

• 01Use it above a list or table that people narrow down by several fields, like issues, orders or files.
• 02Keep field names to one or two words, and order fields by how often people use them.
• 03Order each field's values the way people think of them: a workflow in its order, people by name, sizes from small to large.
• 04Show the applied filters next to the button, such as chips people can remove, so the list never looks mysteriously short.
• 05For a single yes-or-no filter, a switch or a checkbox beside the list is quicker.

Examples

Applied as chips

The component only picks filters. Here the app shows each applied field as a chip beside the button, with a button to remove it.

Search button

search="button" swaps the search box for a Search filters button. Using it slides the whole menu, header and body, over to the search state, which lists every value until you type. Back, Escape or Backspace slides it home. Typing a letter on the menu starts a search too.

Default

The menu on its own, keeping its own state.

With selections

defaultValue starts with values chosen. The fields that have any show a count. The trigger's content is yours, here with a dot to say filters are on.

Keyboard only

Opened from the keyboard: arrows move, Right opens a field, Enter ticks a value, and Left or Backspace goes back to the field it came from.

No matches

A search with no results says so, using emptyText.

Do's and don'ts

API reference

Data attributes

Accessibility

• 01Focus goes to the search box when the menu opens, and stays there. The box is a combobox, and aria-activedescendant points to the highlighted row, so screen readers read each row as the arrows move.
• 02With the search button, the list takes focus instead and points at the highlighted row itself, and the button is one Tab away. Entering search moves focus into the search box; leaving it moves focus back to the list.
• 03Values are options in a multi-select listbox, announced as selected or not. Each field is read with how many of its values are chosen and that it opens its values.
• 04A search announces how many results it found.
• 05Escape steps back one level at a time, and the last press returns focus to the Filter button.
• 06Rename every piece of text for your product's language: the trigger with triggerLabel, the popup with label, and the search box with searchLabel and placeholder.

Related components

• SelectIn fibo's Storybook
• CheckboxIn fibo's Storybook
• Chapter scrubberA rail of marks that swell under the pointer like the Dock, previewing the chapter at the crest.

References

• Base UI Popover, for the popup
• WAI-ARIA combobox pattern
• Motion for React, for the view transitions