# Search and filtering

Helps people find a record by what they remember, with results that follow the typing.

* Kind: pattern
* Page: https://design.werklist.com/patterns/search
* Version: 2.1.2

## When to use it

* A search field above the list it filters
* The command palette for all of WerkOS

## When not to use it

* A search field that does not name what it searches
* Clearing the results on each key

## Rules

* Search from the second character, a moment after the typing stops.
* The results always match what is in the field.
* Mark the words that matched.
* Keep the query in the address, so a shared link opens the same results and Back returns to them.
* Put the closest match first, and group results by kind.
* Filters sit beside the search field and apply at once. One control clears them all.
* A failed search is not an empty one and never shows the empty state.
* On a phone, search takes over the header until the person taps Cancel.

## States

* Idle: The placeholder names what the field searches: Search candidates
* Typing: The search starts from the second character, a moment after the typing stops
* Waiting: The earlier results stay in view, dimmed, until the new ones arrive
* Results: Closest match first, grouped by kind, matched words marked
* Nothing matches: Names the search and the next step, such as Clear filters
* Failed: The earlier results stay under the line 'Search did not finish.' and a Try again button. The empty state does not show.

## Keyboard

* Cmd+K or Ctrl+K: Opens the command palette
* /: Moves focus to the search field of the module
* Up and Down arrows: Move through the results in the palette
* Enter: Opens the highlighted result
* Escape: Clears the query, then closes

## Accessibility

* In the command palette the field tells a screen reader which result is highlighted.
* When the results settle, a screen reader hears how many there are.

## Content

* Nothing matches: 'No candidates match “welder Kathmandu”.' with Clear filters
* Failed: 'Search did not finish.' with Try again
* Active filters in words: Status is Offer sent

## Tokens

* --text-muted
* --focus-ring