{
  "title": "Search and filtering",
  "path": "/patterns/search",
  "url": "https://design.werklist.com/patterns/search",
  "text": "https://design.werklist.com/agent/patterns/search",
  "summary": "How people find records: where search sits, how results arrive, and what an empty, slow or failed search says.",
  "version": "2.1.2",
  "kind": "pattern",
  "name": "Search and filtering",
  "purpose": "Helps people find a record by what they remember, with results that follow the typing.",
  "use": [
    "A search field above the list it filters",
    "The command palette for all of WerkOS"
  ],
  "avoid": [
    "A search field that does not name what it searches",
    "Clearing the results on each key"
  ],
  "states": [
    {
      "name": "Idle",
      "change": "The placeholder names what the field searches: Search candidates"
    },
    {
      "name": "Typing",
      "change": "The search starts from the second character, a moment after the typing stops"
    },
    {
      "name": "Waiting",
      "change": "The earlier results stay in view, dimmed, until the new ones arrive"
    },
    {
      "name": "Results",
      "change": "Closest match first, grouped by kind, matched words marked"
    },
    {
      "name": "Nothing matches",
      "change": "Names the search and the next step, such as Clear filters"
    },
    {
      "name": "Failed",
      "change": "The earlier results stay under the line 'Search did not finish.' and a Try again button. The empty state does not show."
    }
  ],
  "keys": [
    {
      "key": "Cmd+K or Ctrl+K",
      "action": "Opens the command palette"
    },
    {
      "key": "/",
      "action": "Moves focus to the search field of the module"
    },
    {
      "key": "Up and Down arrows",
      "action": "Move through the results in the palette"
    },
    {
      "key": "Enter",
      "action": "Opens the highlighted result"
    },
    {
      "key": "Escape",
      "action": "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"
  ],
  "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."
  ],
  "tokens": [
    "--text-muted",
    "--focus-ring"
  ]
}