Searchable dropdown
A searchable dropdown lets users type to filter a long list of options and select one of them.
- Madrid
- Malmö
- Marseille
Usable — may still change
The searchable dropdown is an input-driven selection component that combines a text field with a filterable list of options. Users type to narrow down a long list and select one item from the filtered results. It handles large or dynamic option sets where scrolling through a static list would be impractical, and it bridges the gap between a free-text input and a standard dropdown: the search is fast and intuitive, but only a value from the predefined set can be selected.
Anatomy
Section titled “Anatomy”- Madrid
- Milan
- No results found, please try another city.
- Label
- Text area
- Icon
- Helper text
- List
- No results
When to use it
Section titled “When to use it”Use a searchable dropdown when:
- The list holds more than 7–10 options and scrolling the full list would be tedious.
- The options come from a dynamic or API-driven source (for example countries, users or product names).
- The user likely knows, or can partially recall, the value they are looking for.
- Keyboard-first users prefer to type rather than click.
- Typeahead adds meaningful value to the task flow.
Avoid it when:
- The list has fewer than 5–7 options — a dropdown or radio group is clearer and faster.
- All options need to be visible at once for comparison — use a list or segmented control.
- The input accepts free text that isn’t limited to a predefined set — use a plain field or a search field.
- The choice is a simple yes or no — use a toggle, checkbox or radio.
- The context is a mobile form with little vertical space — check whether a native select or a bottom sheet picker works better.
Search field vs searchable dropdown vs dropdown
Section titled “Search field vs searchable dropdown vs dropdown”Must the user select from a predefined, closed list?
If no, use a search field.
Are there more than 7–10 options in that list?
If no, use a dropdown or radio buttons.
Does the user know the name of what they are looking for beforehand?
If yes, use a searchable dropdown. If no, use a categorized dropdown or a modal or picker.
Properties
Section titled “Properties”Label
Identifies the expected data. It sits inside the empty field and moves to the top-left corner, smaller, once the field is active or holds a value — the same behaviour as the Field.
Text area
Holds the query while the user types, and the selected option once one is chosen. While the field is active and empty it shows a placeholder that says what can be searched for.
Icon
The chevron in the trigger. It points down while the list is closed and flips up while it is open.
Helper text
Optional supporting text under the field, with or without an icon.
Required
A required field shows a red asterisk next to its label.
Error
When the user leaves a required field empty, the field turns to its error state and the helper text is replaced by the error message and the instructions to solve it, with the error icon.
State
Rested, Hover, Active, Focus, Error and Disabled, each empty or filled. Active opens the list; Focus highlights the field for keyboard users; Disabled shows the field but makes it non-interactive, for example until a previous step is completed.
List
A floating List of options opens under the field while it is active. As the user types, the list narrows to the matching options and the best match is highlighted. When nothing matches, the list shows a single “No results” row.
Width
Set the width to the expected length of the content. The content never grows the field: the container masks the text.
Text overflow
The value stays on one line. At rest, text past the edge ends in an ellipsis. While active, the text scrolls so the cursor stays visible.
Selecting an option
Section titled “Selecting an option”- The user clicks the field and the list opens.
- The user types, the list filters, and the best match is highlighted.
- The user selects an option. The list closes and the field is filled.
- If the user leaves a required field empty, it shows its error.
When the field already holds a value, the user can browse the list as normal; the value only changes once a new option is selected.
Best practices
Section titled “Best practices”Do
Provide relevant choices, and let users browse the list without typing anything. Keep the list in step with the search, so users can see why each result appears. Always show a clear message when nothing matches.
Don't
Don’t make the list items wider than the field. Don’t use it for short lists — use a dropdown or radio buttons instead. Don’t show so many options at once that the screen feels crowded, especially on mobile.
A searchable dropdown has no classes of its own. It is a Field whose input is a combobox, with a Dropdown panel holding a List of options. The examples below show the panel open; the Recipe wires it up.
<div class="tng-field"> <div class="tng-field-control"> <label class="tng-field-control-label" for="searchable-dropdown-default" > City </label> <input class="tng-field-control-input" id="searchable-dropdown-default" type="text" role="combobox" aria-autocomplete="list" aria-expanded="true" aria-controls="searchable-dropdown-default-listbox" aria-activedescendant="searchable-dropdown-default-madrid" autocomplete="off" value="Ma" /> <button class="p-absolute tng-icon-button is-ghost" type="button" tabindex="-1" aria-label="Cities" aria-expanded="true" aria-controls="searchable-dropdown-default-listbox" > <i class="tng-icon icon-chevron-up" aria-hidden="true"></i> </button> </div></div><div class="tng-dropdown"> <ul class="tng-list tng-has-dividers" id="searchable-dropdown-default-listbox" role="listbox" aria-label="Cities" > <li class="tng-list-option is-active" id="searchable-dropdown-default-madrid" role="option" aria-selected="false" > <span>Madrid</span> </li> <li class="tng-list-option" role="option" aria-selected="false"> <span>Milan</span> </li> <li class="tng-list-option" role="option" aria-selected="false" hidden > <span>Paris</span> </li> </ul></div>- Madrid
- Milan
- Paris
Elements
Section titled “Elements”A tng-field-control-input with role="combobox". With .is-lg on the label, the label sits inside the empty field and floats above it on focus; keep .is-lg while the input is empty and remove it once it has a value.
Placeholder
Section titled “Placeholder”A placeholder floats the label as soon as it’s set, so add it when the input gets focus and remove it on blur. It takes the muted foreground colour.
Icon button
Section titled “Icon button”The chevron is a tng-icon-button in the field’s trailing slot. It needs p-absolute, and tabindex="-1" keeps it out of the tab sequence — the input is the only stop. Swap icon-chevron-down for icon-chevron-up while the list is open.
Helper and error text
Section titled “Helper and error text”Put a tng-field-info under the control, and swap it for a tng-field-error when validation fails.
<div class="tng-field"> <div class="tng-field-control"> <label class="tng-field-control-label is-lg" for="searchable-dropdown-helper" > City </label> <input class="tng-field-control-input" id="searchable-dropdown-helper" type="text" role="combobox" aria-autocomplete="list" aria-expanded="false" aria-describedby="searchable-dropdown-helper-info" autocomplete="off" /> <button class="p-absolute tng-icon-button is-ghost" type="button" tabindex="-1" aria-label="Cities" aria-expanded="false" > <i class="tng-icon icon-chevron-down" aria-hidden="true"></i> </button> </div> <div class="tng-field-info" id="searchable-dropdown-helper-info"> <span>Start typing to filter the list.</span> </div></div>Options
Section titled “Options”Each option is a tng-list-option with role="option".
No results
Section titled “No results”When no option matches, show one muted row in place of the options.
<div class="tng-dropdown"> <ul class="tng-list" role="listbox" aria-label="Cities"> <li class="tng-list-option fg-muted" role="option" aria-disabled="true" > No results found, please try another city. </li> </ul></div>- No results found, please try another city.
States
Section titled “States”Filtered
Section titled “Filtered”Put hidden on the options that don’t match the query.
Highlighted
Section titled “Highlighted”.is-active marks the best match, or the option the arrow keys moved to. Set it together with aria-activedescendant on the input — DOM focus never leaves the input, so this is the only focus indicator the option gets.
Selected
Section titled “Selected”aria-selected="true" gives the option its selected background.
<div class="tng-dropdown"> <ul class="tng-list tng-has-dividers" role="listbox" aria-label="Cities" > <li class="tng-list-option is-active" role="option" aria-selected="false" > <span>Madrid</span> </li> <li class="tng-list-option" role="option" aria-selected="true"> <span>Milan</span> </li> </ul></div>- Madrid
- Milan
.is-invalid on the control, or :user-invalid on a required input, shows the error state.
<div class="tng-field"> <div class="tng-field-control is-invalid"> <label class="tng-field-control-label is-lg" for="searchable-dropdown-error" > City </label> <input class="tng-field-control-input" id="searchable-dropdown-error" type="text" role="combobox" aria-autocomplete="list" aria-expanded="false" aria-invalid="true" aria-describedby="searchable-dropdown-error-message" autocomplete="off" required /> <button class="p-absolute tng-icon-button is-ghost" type="button" tabindex="-1" aria-label="Cities" aria-expanded="false" > <i class="tng-icon icon-chevron-down" aria-hidden="true"></i> </button> </div> <div class="tng-field-error" id="searchable-dropdown-error-message"> <i class="tng-icon icon-error" aria-hidden="true"></i> <span>Select a city.</span> </div></div>Disabled
Section titled “Disabled”Disable both the input and the icon button.
<div class="tng-field-control"> <label class="tng-field-control-label is-lg" for="searchable-dropdown-disabled" > City </label> <input class="tng-field-control-input" id="searchable-dropdown-disabled" type="text" role="combobox" aria-autocomplete="list" aria-expanded="false" autocomplete="off" disabled /> <button class="p-absolute tng-icon-button is-ghost" type="button" tabindex="-1" aria-label="Cities" disabled > <i class="tng-icon icon-chevron-down" aria-hidden="true"></i> </button></div>Recipe
Section titled “Recipe”- Amsterdam
- Antwerp
- Athens
- Barcelona
- Berlin
- Brussels
- Budapest
- Copenhagen
- Dublin
- Lisbon
- Madrid
- Milan
- Paris
- Prague
- Rome
- Stockholm
- Vienna
- Warsaw
- No results found, please try another city.
The searchable dropdown follows the WAI-ARIA APG editable combobox with list autocomplete and meets WCAG 2.1 AA. Every field has a visible label and a clear focus indicator, every action works from the keyboard alone, and assistive technology hears the label, the state (disabled or error), the helper text and which option is highlighted — whether the user is looking at the list, listening to it, or typing into it.
For designers
Section titled “For designers”- All list items and states must keep accessible contrast on every supported surface. Source: WCAG 1.4.3 Contrast (Minimum).
- Focus styles must stay visible, meet contrast requirements on every supported surface, and be clearly distinguishable from hover. Source: WCAG 2.4.7 Focus Visible.
- Use semantic colour tokens (for example
foreground/neutral/default) rather than fixed values, so the component adapts across themes and surfaces. - Interactive areas must be at least 44 px high. Source: WCAG 2.5.8 Target Size (Minimum).
For developers
Section titled “For developers”The input is the only element that takes DOM focus. Typing filters the list and highlights the best match; the arrow keys move the highlight through the visible options, and Enter commits it. The highlighted option is announced through aria-activedescendant, so the list never receives focus and the user can keep typing at any moment. Only a listed value is accepted: on blur, free text falls back to the last selected option, and a required field left empty shows its error. The per-element roles, names and states are in Labelling elements below.
Keyboard interaction
Section titled “Keyboard interaction”| Key | Action |
|---|---|
| Printable characters | Type into the input, open the list and filter it; the best match is highlighted |
| ↓ / ↑ | Open the list, then move the highlight to the next / previous option, wrapping around |
| Alt + ↓ | Open the list without moving the highlight |
| Enter | Select the highlighted option and close the list |
| Escape | Close the list; when it’s already closed, clear the input. Focus stays on the input |
| Space | Type a space |
| Tab / Shift + Tab | Close the list and move to the next / previous control |
Focus order
Section titled “Focus order”The field is a single tab stop: the input. The icon button sits outside the tab sequence and the options are reached with the arrow keys, not Tab. Selecting an option keeps focus on the input, now filled, and clicking outside closes the list without moving focus. Source: WCAG 2.4.3 Focus Order.
Where Figma’s notes differ
Section titled “Where Figma’s notes differ”The Figma page describes a different keyboard model. These recipes follow the APG pattern instead, because it keeps the input editable at every step:
- Tab through the options. Figma has Tab move through the list once it is open. Here, Tab leaves the field and closes the list; the arrow keys move through the options.
- Space selects. Figma lets Enter or Space select the highlighted option. Here, Space types a space, since many values contain one; Enter selects.
- The list receives focus. Figma moves focus into the list, to the selected or first option. Here, focus stays in the input and the highlighted option is conveyed with
aria-activedescendant. - Escape returns to the previous element. Figma returns focus to the previous element on Escape. Here, Escape closes the list and focus stays on the input.
Labelling elements
Section titled “Labelling elements”Input
A text <input> with role="combobox", aria-autocomplete="list", aria-controls pointing at the listbox, and aria-expanded kept in sync with the list. While an option is highlighted, aria-activedescendant holds its id. Name it with a <label for>; describe it with aria-describedby pointing at the helper text, or at the error message with aria-invalid="true" once validation fails. Set autocomplete="off" so the browser’s own suggestions don’t cover the list.
Icon button
A <button type="button"> with tabindex="-1", aria-expanded and aria-controls matching the input’s, and an aria-label naming the list ("Cities"). The chevron inside is aria-hidden="true".
Listbox
role="listbox" with an aria-label or aria-labelledby, so it doesn’t announce as an unnamed list.
Options
role="option" with a unique id, aria-selected="true" on the selected one and "false" on the rest. Each option takes its name from its text. Filtered-out options carry hidden, which also removes them from the accessibility tree.
No results
An option with aria-disabled="true", so it is announced but can’t be selected or highlighted.
Source: WCAG 4.1.2 Name, Role, Value.