Skip to contentSkip to navigation
DocsDocs

Filtering and search

Let people narrow a list or a table to what they want, and undo it in one step.

BetaSince 1.0.0
On this page

Overview

Show code, SearchAndFilters.tsx

Variants

Filters in a popover

A Filters button, with a count of the filters in use, opens a Popover of checkboxes in groups that apply as they change.

Show code, FilterPanel.tsx

Filters in use

Each filter in use is a token named after it, "Status: Open", beside Add filter and Clear filters. A token is a small button with a close cross that removes it.

Show code, ActiveFilters.tsx

Anatomy

  1. Toolbar

  2. Search

  3. Filter

  4. More filters

  5. Count

Show code, FilteringAnatomy.tsx

A search and a few filters sit in the PageHeader's toolbar, above the results.

Behaviour

State in the address

Write the query and the filters into the address through the router, so a reload, the back button and a shared link show the same results.

Adapting to width

Narrower than a medium window, the filters move into a Sheet opened by a Filters button, with its own count; the search stays in view.

Show code, NarrowFilters.tsx

Rules

Each choice filters at once, and a count says how many match.

Use it when

  • A list or a table long enough to look for items in
  • Narrowing items by what they are, such as status, owner or type

Built from

Page, TextField, Select, Combobox, Popover, Checkbox, Sheet, Radio, Menu, Button, Badge, List

DoEach choice filters at once, and a count says how many match.
Show code, AppliedAtOnce.tsx
CautionAn Apply button for quick filters: nothing says what will match.
Show code, WaitsForApply.tsx

Apply button

Keep an Apply button only for a slow or costly query, and say what it shows: "Show 12 projects".

Count what the filters leave, never one page of a table. Never hide the search in a menu or a sheet.

Content

Name each control after what it does, and count in the items' units.

  • Label the search with what it searches, "Search projects".
  • Name the option for all after the filter, "Any status", rather than "All".
  • Count in the units of the items, "3 projects of 6".
  • Say Clear filters for removing them all.

Accessibility

Focus and keyboard

Typing filters without moving focus, and the count is announced politely.

  • The popover takes focus as it opens.
  • Tab past its last checkbox closes it, and Esc returns focus to its button.
  • When Clear filters or a token goes, focus moves to the search, or to the next token.

Related