Skip to content
BigBang

Popular

    ↑↓Navigate↵OpenEscClose
    TR

    Components

    FilterBar

    Filter controls for a list or table: applied-filter chips, a result count and one-click clear.

    Storybook
    Storybook
    Source
    Source

    When to use

    Section titled “When to use”

    FilterBar sits above a list or table and lets users narrow the records: search by name, pick a status, a few categories, a switch such as “mine only”. Users see what is filtered from the chips and reset it in one click.

    When not to use

    Section titled “When not to use”
    • For a single field: one search box needs only TextInput or InputGroup.
    • For many complex conditions: a query builder with logical grouping is not the job of FilterBar.
    • To sort the data itself: sorting belongs in the table header.
    • For in-page navigation: use Tabs to switch between views of the same data.

    Anatomy

    Section titled “Anatomy”
    1. Root: a region named with role="search".
    2. Search (FilterBar.Search): a text box with an icon; its label is visually hidden and the placeholder repeats it.
    3. Fields (FilterBar.Field): Select for select, a popover checkbox group for multi-select, Toggle for toggle.
    4. More (FilterBar.More): on narrow screens a button and a panel for the other fields.
    5. Apply (FilterBar.Apply): Apply and Reset in batch mode.
    6. Clear (FilterBar.Clear): only when a filter is applied.
    7. Chips (FilterBar.Applied): "{field}: {value}" chips.
    8. Result count (FilterBar.ResultCount): “12 results”.

    Behaviour

    Section titled “Behaviour”
    • In instant mode every change is reported at once through onValueChange, and so is every keystroke in the search box. If typing starts a request, debounce the call yourself.
    • In batch mode the draft stays local; Apply, Reset and Enter handle it. Removing a chip and clearing apply at once.
    • In a multi-select every chosen option is its own chip.
    • “Clear filters” returns to defaultValue; without it every field is emptied. After clearing, focus moves to the first control.
    • Removing the last chip also moves focus to the first control.
    • While loading, the result count becomes a placeholder and is not announced.
    • Below 1024 px the search stays in the row and the other fields go under “More filters”.

    Guidelines

    Section titled “Guidelines”

    Keep the common filters visible

    Section titled “Keep the common filters visible”

    Keep the three or four most used filters in the row; leave the rare ones under “More filters”.

    DoSearch and two common filters are visible; the result count is clear.
    Don'tNo result count; users cannot tell whether the filter worked.

    Choose batch apply for expensive queries

    Section titled “Choose batch apply for expensive queries”

    If every change starts a long query use batch; for light filtering instant feels smoother.

    DoSeveral fields are chosen and applied once.
    Don'tAn Apply button for a single search box is an extra step.

    Content

    Section titled “Content”
    • Make field labels short nouns: “Status”, “Category”, “Owner”.
    • Keep the search label short, such as “Search”; let the placeholder say what is searched: “Search by name”.
    • Write options in sentence case and leave the “All” option alone; the library adds it.
    • When writing to the URL, think about what search text can contain: do not keep searches with personal data in the URL. That decision is the app’s.
    Section titled “Related components”
    • Tag: the applied-filter chips are drawn with this component.
    • Select: for single-choice fields.
    • Toggle: for on-off filters.
    • Table: to show the filtered records.