Skip to content
Download assets

Search field

A search field narrows a list as you type. Put it above the list it searches and name that list in the placeholder.

6 candidates

  • Bishnu TamangWelder, Nepal
  • Priya NairCare assistant, India
  • Maricel SantosCare assistant, Philippines
  • Marko PetrovićElectrician, Serbia
  • Emina HodžićWelder, Bosnia and Herzegovina
  • Anil GurungWarehouse operative, Nepal

When to use it

Use a search field to find records in a list on the screen: candidates, companies, the items of a board. The placeholder names the list, such as Search candidates.

To search all of WerkOS, use the command palette. To choose one value in a form, use a combobox.

Anatomy

The search field is a text field with a search icon at its start. The clear button appears once there is text and empties the field in one press.

In a toolbar the field has no visible label, so its accessible name repeats the placeholder.

With a search typed in, and the compact size for a toolbar.
Fill and focus
as the text field
Height
44 px
Height in a toolbar, with a mouse
36 px
Search icon
16 px, 12 px from the start
--text-muted
Text starts at
36 px
Clear button
32 px, 6 px from the end
Corner radius
8 px
--radius-lg

How results arrive

Results follow the typing from the second character, a moment after the last key, and a line under the field says how many there are. The earlier results stay on screen and dim while the next ones load, so the list does not blank on each key. Enter keeps the query in the browser history, so Back returns to it.

Wait after the last key
120 ms
Shortest query
2 characters
Earlier results while loading
dimmed to 60 percent
Loading indicator
only after 150 ms

Keyboard

The slash works when focus is not already in a field.

/
Moves focus to the search field
Escape
Clears the text, then leaves the field
Enter
Keeps the query in the history
Down arrow
Moves into suggestions, when the field has them

On a phone

On a phone, search is a mode. Tapping the field widens it across the header, hides the other controls and shows Cancel. Cancel empties the field and brings the header back.

Permitted and not permitted

Permitted

  • Search candidates

    The recruiter knows what the results will hold.

Not permitted

  • Search, on its own, in a module with several lists

    The recruiter has to guess what is being searched.

NextSelect

Search field

Filters a visible list, or finds records, as the person types.

  • Kind: component
  • Name: SearchField
  • Page: https://design.werklist.com/components/search-field
  • Version: 2.1.2

When to use it

  • Above a list it filters, with the list named in the placeholder
  • Inside the command palette

When not to use it

  • Choosing a value in a form: use a combobox
  • A search that does not name what it searches

Rules

  • Search from 2 characters, 120 ms after the last key
  • An answer that arrives after a newer one is dropped
  • The earlier results stay on screen, dimmed, while the next ones load
  • The query is kept in the address of the page

Anatomy

  • Control: a text field of type search, with the fill and the focus of the text field. The browser's own clear button is hidden (--input-border)
  • Height: 44 px, or 36 px in a toolbar with a mouse, and 44 px on a touch screen
  • Search icon: 16 px, 12 px from the start (--text-muted)
  • Text inset: 36 px at the start, and 44 px at the end while the clear button shows
  • Clear button: an icon button of 32 px with a cross, named Clear search, 6 px from the end, shown only when the field holds text
  • Corner radius: 8 px (--radius-lg)

Sizes

  • md: height 44 px, type 14 px on 20 px
  • compact: height 36 px with a mouse and 44 px on a touch screen, type 14 px on 20 px

States

  • Empty: The placeholder in the muted ink, and no clear button (--text-muted)
  • Filled: The clear button shows (--text)
  • Loading: The earlier results dim to 60 percent. A loading indicator appears only after 150 ms
  • Focus, disabled: As the text field, with no hover state (--brand-blue, --text, --text-muted)
  • Search on a phone: The field spans the header, the other controls hide and a Cancel button shows

Keyboard

  • /: Moves focus to the search field when focus is not in a field
  • Escape: Clears the text. With the field empty, leaves the field or the search on a phone
  • Enter: Keeps the query in the browser history, so Back returns to it
  • Down arrow: Moves into the suggestions when the field has them. The field is then a combobox with aria-activedescendant

Accessibility

  • The field sits in a search landmark
  • Its accessible name repeats the placeholder when there is no visible label
  • aria-keyshortcuts="/" on the field that takes the slash
  • The number of results sits in a role="status" region under the field and is read when the results settle

Content

  • The placeholder names what is searched: Search candidates, Search this board
  • The clear button is named Clear search
  • On a phone the Enter key reads Search. The field offers no autofill and no spelling correction

Tokens

  • --glass-fill-input
  • --input-border
  • --brand-blue
  • --text-muted
  • --radius-lg

JSON

{
  "title": "Search field",
  "path": "/components/search-field",
  "url": "https://design.werklist.com/components/search-field",
  "text": "https://design.werklist.com/agent/components/search-field",
  "summary": "A field for finding records, with a search icon, a clear button and results that follow the typing.",
  "version": "2.1.2",
  "kind": "component",
  "name": "SearchField",
  "purpose": "Filters a visible list, or finds records, as the person types.",
  "use": [
    "Above a list it filters, with the list named in the placeholder",
    "Inside the command palette"
  ],
  "avoid": [
    "Choosing a value in a form: use a combobox",
    "A search that does not name what it searches"
  ],
  "anatomy": [
    {
      "part": "Control",
      "measure": "a text field of type search, with the fill and the focus of the text field. The browser's own clear button is hidden",
      "token": "--input-border"
    },
    {
      "part": "Height",
      "measure": "44 px, or 36 px in a toolbar with a mouse, and 44 px on a touch screen"
    },
    {
      "part": "Search icon",
      "measure": "16 px, 12 px from the start",
      "token": "--text-muted"
    },
    {
      "part": "Text inset",
      "measure": "36 px at the start, and 44 px at the end while the clear button shows"
    },
    {
      "part": "Clear button",
      "measure": "an icon button of 32 px with a cross, named Clear search, 6 px from the end, shown only when the field holds text"
    },
    {
      "part": "Corner radius",
      "measure": "8 px",
      "token": "--radius-lg"
    }
  ],
  "sizes": [
    {
      "name": "md",
      "height": "44 px",
      "type": "14 px on 20 px"
    },
    {
      "name": "compact",
      "height": "36 px with a mouse and 44 px on a touch screen",
      "type": "14 px on 20 px"
    }
  ],
  "states": [
    {
      "name": "Empty",
      "change": "The placeholder in the muted ink, and no clear button",
      "tokens": [
        "--text-muted"
      ]
    },
    {
      "name": "Filled",
      "change": "The clear button shows",
      "tokens": [
        "--text"
      ]
    },
    {
      "name": "Loading",
      "change": "The earlier results dim to 60 percent. A loading indicator appears only after 150 ms"
    },
    {
      "name": "Focus, disabled",
      "change": "As the text field, with no hover state",
      "tokens": [
        "--brand-blue",
        "--text",
        "--text-muted"
      ]
    },
    {
      "name": "Search on a phone",
      "change": "The field spans the header, the other controls hide and a Cancel button shows"
    }
  ],
  "keys": [
    {
      "key": "/",
      "action": "Moves focus to the search field when focus is not in a field"
    },
    {
      "key": "Escape",
      "action": "Clears the text. With the field empty, leaves the field or the search on a phone"
    },
    {
      "key": "Enter",
      "action": "Keeps the query in the browser history, so Back returns to it"
    },
    {
      "key": "Down arrow",
      "action": "Moves into the suggestions when the field has them. The field is then a combobox with aria-activedescendant"
    }
  ],
  "accessibility": [
    "The field sits in a search landmark",
    "Its accessible name repeats the placeholder when there is no visible label",
    "aria-keyshortcuts=\"/\" on the field that takes the slash",
    "The number of results sits in a role=\"status\" region under the field and is read when the results settle"
  ],
  "content": [
    "The placeholder names what is searched: Search candidates, Search this board",
    "The clear button is named Clear search",
    "On a phone the Enter key reads Search. The field offers no autofill and no spelling correction"
  ],
  "tokens": [
    "--glass-fill-input",
    "--input-border",
    "--brand-blue",
    "--text-muted",
    "--radius-lg"
  ],
  "rules": [
    "Search from 2 characters, 120 ms after the last key",
    "An answer that arrives after a newer one is dropped",
    "The earlier results stay on screen, dimmed, while the next ones load",
    "The query is kept in the address of the page"
  ]
}

Raw file: https://design.werklist.com/agent/components/search-field