Dropdown
A dropdown displays a list of selectable options in a floating panel, allowing users to choose from predefined choices in a compact interface.
- Hybrid
- Plug-in Hybrid
- Electric
Ready to use
A Dropdown lets users select an option from a list of choices that appears when they interact with a trigger. It helps keep interfaces clean by hiding secondary or large sets of options until needed, which makes it useful when space is limited or when the user needs to choose from a set of mutually exclusive actions or values. The component is fully responsive and intentionally designed to be used across all viewports.
Anatomy
Section titled “Anatomy”- Hybrid
- Plug-in Hybrid
- Electric
- Trigger
- Chevron
- List
- Selected option
When to use it
Section titled “When to use it”Use the Dropdown when:
- You need to offer 4–12 options without overwhelming the interface.
- The selection doesn’t need to be immediately visible until the user interacts.
- The user has to switch between predefined values or trigger an action.
- Space is constrained and a compact UI is preferred.
- You need to organise secondary actions tied to a primary object or context.
Avoid the Dropdown when:
- The user needs to compare all options at once — consider radio buttons or a list.
- The selection needs frequent or rapid access — a persistent UI element is better.
- The action is a highly visible or critical CTA — use an explicit button.
- The options include complex content like large images or long descriptions — use a menu or a select list instead.
Properties
Section titled “Properties”State
Rested, Hover, Filled, Disabled, and Focus. The filled variant carries a subtle background so users can see at a glance which dropdowns hold a value; focus shows a 2 px outline so the trigger stays reachable from the keyboard.
Label
A persistent label sits above the trigger and names the selection. Keep it visible while the user interacts — placeholder-only labels fail when the user comes back to revise the form.
Helper text
Optional one-line helper text beneath the trigger. Use it to communicate constraints or examples (for example “Choose your preferred year”), not to repeat the label.
List
The list of options that opens beneath the trigger. Keep option labels short and scannable, and organise long lists alphabetically or by category to reduce cognitive load.
Chevron
The direction indicator inside the trigger. It points down when the list is closed and flips up while it is open.
Platform considerations
Section titled “Platform considerations”Desktop
The menu opens beneath the trigger and matches its width by default. Adapt the width to fit the longest option where clarity matters more than alignment.
Tablet
Same behaviour as desktop. Don’t auto-open on focus — it’s disorienting and doesn’t reflect typical usage patterns.
Mobile
The dropdown often promotes to the native picker on mobile. Keep the visible trigger tall enough for comfortable tapping and ensure clickability is clear without relying on hover.
Best practices
Section titled “Best practices”Treat the dropdown as a way to compress a known set of choices — not as a hiding place for important content.
Do
Keep option labels concise and easy to scan, organise long lists alphabetically or by category, use placeholder text that clearly indicates the expected action (“Select model” rather than “Choose”), pre-select an option only when there’s a strong default, keep terminology consistent across dropdowns in the product, and adapt the trigger width to fit the longest option when clarity matters.
Don't
Don’t overload the dropdown with too many items (a searchable dropdown fits very long lists), don’t mix unrelated content types inside the list, don’t use vague or repetitive labels like “Option 1” or “Item”, don’t rely on hover to indicate state on touch devices, don’t hide critical information inside a dropdown if it affects the user’s decision, and don’t auto-open on focus.
Content guidelines
Section titled “Content guidelines”Write option labels that stand on their own — users shouldn’t need surrounding context to understand them. Keep them short and scannable (one line wherever possible), use sentence case for readability, and make sure the wording is parallel across the menu (all nouns or all verbs). Use placeholder text that tells the user what kind of choice the dropdown holds (“Select model”), and reserve helper text for constraints or examples rather than restating the label.
A dropdown is a composition: a trigger, the tng-dropdown panel, and a List inside it. tng-dropdown paints the panel — surface, elevation and inline padding — and everything in it comes from other components. The examples below show the panel open; the Recipes wire it to a popover.
<div class="tng-field-control"> <button class="tng-field-control-button" aria-expanded="true"> Zone </button> <i class="tng-icon icon-chevron-down"></i></div><div class="tng-dropdown"> <ul class="tng-list tng-has-dividers" role="listbox" aria-label="Zone" > <li class="tng-list-option" role="option" aria-selected="true"> TZ1 </li> <li class="tng-list-option" role="option">TZ2</li> <li class="tng-list-option" role="option">TZ3</li> </ul></div>- TZ1
- TZ2
- TZ3
Elements
Section titled “Elements”Trigger
Section titled “Trigger”Open the panel from a Field control button inside a form, or from a Chip as a filter. The trigger owns the label, helper text, required mark and its own states.
<button class="tng-chip" aria-expanded="true"> Body type <i class="tng-icon icon-chevron-down" aria-hidden="true"></i></button><div class="tng-dropdown"> <ul class="tng-list tng-has-dividers" role="listbox" aria-label="Body type" > <li class="tng-list-option" role="option">Hatchback</li> <li class="tng-list-option" role="option">Saloon</li> <li class="tng-list-option" role="option">SUV</li> </ul></div>- Hatchback
- Saloon
- SUV
Back button
Section titled “Back button”When an option opens a second level, put a borderless tertiary Button above the list to return to the first.
<div class="tng-dropdown"> <button class="tng-button is-tertiary is-ghost"> <i class="tng-icon icon-arrow-left tng-rtl-flip-x" aria-hidden="true" ></i> Back </button> <ul class="tng-list tng-has-dividers" role="listbox" aria-label="Hybrid" > <li class="tng-list-option" role="option"> Yaris Hybrid <i class="tng-icon icon-chevron-right tng-rtl-flip-x" aria-hidden="true" ></i> </li> <li class="tng-list-option" role="option"> C-HR Hybrid <i class="tng-icon icon-chevron-right tng-rtl-flip-x" aria-hidden="true" ></i> </li> <li class="tng-list-option" role="option"> RAV4 Hybrid <i class="tng-icon icon-chevron-right tng-rtl-flip-x" aria-hidden="true" ></i> </li> </ul></div>- Yaris Hybrid
- C-HR Hybrid
- RAV4 Hybrid
Scrolling
Section titled “Scrolling”Cap a long list with max-block-size and let tng-overflow-scroll draw the scrollbar. Figma caps it at 455px.
<div class="tng-dropdown"> <ul class="tng-list tng-has-dividers tng-overflow-scroll" role="listbox" aria-label="Zone" style="max-block-size: 200px" > <li class="tng-list-option" role="option">TZ1</li> <li class="tng-list-option" role="option">TZ2</li> <li class="tng-list-option" role="option">TZ3</li> <li class="tng-list-option" role="option">TZ4</li> <li class="tng-list-option" role="option">TZ5</li> <li class="tng-list-option" role="option">TZ6</li> <li class="tng-list-option" role="option">TZ7</li> </ul></div>- TZ1
- TZ2
- TZ3
- TZ4
- TZ5
- TZ6
- TZ7
Actions
Section titled “Actions”A multi-select list confirms with a row of buttons under the list: a tertiary one to clear, a primary one to apply.
<div class="tng-dropdown"> <ul class="tng-list" role="listbox" aria-label="Body type" aria-multiselectable="true" > <li class="tng-list-option" role="option" aria-selected="true"> <label class="tng-checkbox-control"> <input type="checkbox" inert checked /> Hatchback </label> </li> <li class="tng-list-option" role="option" aria-selected="false"> <label class="tng-checkbox-control"> <input type="checkbox" inert /> Saloon </label> </li> </ul> <div class="tng-flex gap-4xl pb-xl pi-xl"> <button class="tng-button is-tertiary flex-grow-1"> Clear all </button> <button class="tng-button is-primary flex-grow-1"> Show 12 results </button> </div></div>Content
Section titled “Content”The panel takes any List content. Three shapes cover the Figma list types.
Simple list
Section titled “Simple list”Text options. Add tng-has-dividers for the line under each one.
<div class="tng-dropdown"> <ul class="tng-list tng-has-dividers" role="listbox" aria-label="Zone" > <li class="tng-list-option" role="option">TZ1</li> <li class="tng-list-option" role="option">TZ2</li> </ul></div>- TZ1
- TZ2
Model list
Section titled “Model list”Options that carry a model image and a powertrain label.
<div class="tng-dropdown"> <ul class="tng-list tng-has-dividers" role="listbox" aria-label="Model" > <li class="tng-list-option" role="option"> <img alt="" src="/_astro/prius.B6m1c0f0.png" /> <div class="tng-list-powertrain"> <div class="tng-list-powertrain-subtitle"> <span class="tng-label is-blue"> <i class="tng-icon icon-plug-droplet" aria-hidden="true" ></i> <span>Plug-in Hybrid</span> </span> <div>333 mi</div> </div> <div class="tng-text-body">Prius</div> </div> </li> </ul></div>-
Plug-in Hybrid333 miPrius
Multi-select
Section titled “Multi-select”Wrap each option in a Checkbox control and mark the list aria-multiselectable. Pair it with Actions.
<div class="tng-dropdown"> <ul class="tng-list" role="listbox" aria-label="Body type" aria-multiselectable="true" > <li class="tng-list-option" role="option" aria-selected="true"> <label class="tng-checkbox-control"> <input type="checkbox" inert checked /> Hatchback </label> </li> <li class="tng-list-option" role="option" aria-selected="false"> <label class="tng-checkbox-control"> <input type="checkbox" inert /> Saloon </label> </li> <li class="tng-list-option" role="option" aria-selected="false"> <label class="tng-checkbox-control"> <input type="checkbox" inert /> Estate </label> </li> </ul></div>States
Section titled “States”Selected
Section titled “Selected”aria-selected="true" on an option, or a checked checkbox inside it, gives it the selected background.
<div class="tng-dropdown"> <ul class="tng-list tng-has-dividers" role="listbox" aria-label="Zone" > <li class="tng-list-option" role="option">TZ1</li> <li class="tng-list-option" role="option" aria-selected="true"> TZ2 </li> </ul></div>- TZ1
- TZ2
Recipes
Section titled “Recipes”Select List
Section titled “Select List”
Powertrain333 miOption 1
Powertrain333 miOption 2
Powertrain333 miOption 3
Checkbox List
Section titled “Checkbox List”Body type
Import the Dropdown component from @tmedxp/react-components.
It provides a single-selection field built from List and ListItem, with a floating list of text options. Selection, positioning and keyboard navigation are managed by the component.
Properties
Section titled “Properties”DropdownProperties extends HTMLAttributes<HTMLDivElement> (excluding className and the native onSelect). Other native attributes, such as id and data-*, are forwarded to the root <div>. When label is omitted, aria-label names both the trigger and list.
All component props are optional.
| Prop | Type | Description | Default |
|---|---|---|---|
items |
ListItemProperties[] |
Options rendered in the list. | [] |
label |
string |
Visible field label, also used to name the trigger and list. | undefined |
labelPosition |
'outside' | 'inside' |
Places the label above the field or inside the trigger. Requires label. |
'outside' |
placeholder |
string |
Text shown before selection; takes precedence over the initial selection. | undefined |
defaultItem |
ListItemProperties |
Initially selected item when no placeholder is supplied. | undefined |
helperText |
string |
Helper text associated with the trigger. | undefined |
required |
boolean |
Shows the required marker and sets aria-required on the list. |
false |
disabled |
boolean |
Disables the trigger and selection. | false |
onSelect |
(item: ListItemProperties) => void |
Called with the full item when an option is selected. | undefined |
className |
ClassValue |
Additional class names for the root field. | undefined |
ListItemProperties
Section titled “ListItemProperties”Use the exported ListItemProperties type for each option. It extends native anchor attributes, with ClassValue for className. Pass options as data; there is no need to render List or ListItem yourself.
| Prop | Type | Description |
|---|---|---|
label |
string |
Visible option text. Supply unique labels: the dropdown compares selected items by label. |
id |
string |
Optional stable identifier, also available in the item passed to onSelect. |
aria-disabled |
boolean | 'true' | 'false' |
Marks an unavailable option. Disabled options cannot be selected and are skipped by arrow navigation. |
onClick |
MouseEventHandler<HTMLAnchorElement> |
Optional item handler. Calling event.preventDefault() cancels selection. |
optionProperties |
ListItemProperties['optionProperties'] |
Attributes for the outer option <li>, including className and style. |
The dropdown manages isSelected and option focus internally. Trailing icons are hidden unless an item explicitly enables showTrailingIcon.
Selection behavior
Section titled “Selection behavior”- Supplying
placeholder, including an empty string, starts with no selected item and takes precedence overdefaultItem. - Without a placeholder, the initial selection is
defaultItem, or the first item when no default is supplied. An empty list has no initial selection. - Selection is internal state. Changing
defaultItemoritemsafter mounting does not reset the current selection; there is no controlled-value prop. - Selecting an enabled option updates the trigger label, closes the list, restores trigger focus and calls
onSelectonce with that item. Initial selection does not callonSelect.
required supplies the visual and ARIA state; it does not add native form validation or submit a form value. Use onSelect to keep the selected item in your form state.
Positioning and scrolling
Section titled “Positioning and scrolling”The panel opens below the field when there is room, flips above when needed and matches the field width within the available viewport space. It uses a native popover and Floating UI with document-relative positioning, so it stays attached during page scrolling without waiting for a JavaScript coordinate update. Positioning also updates on resize and ancestor scrolling.
The list height is limited to the available viewport space. Only the inner list scrolls; the outer panel remains unclipped by ancestor overflow. No additional dropdown stylesheet or manual positioning is needed beyond the component’s styleguide styles.
Keyboard and focus
Section titled “Keyboard and focus”| Input | Behavior |
|---|---|
| Click the trigger | Opens or closes the list. |
| Arrow Up / Arrow Down | Opens the list from the trigger or moves focus between enabled options while it is open. |
| Home / End | Moves to the first or last enabled option while the list is open. |
| Enter / Space | Opens the list from the trigger, or selects the focused option and restores trigger focus. |
| Escape | Closes without changing selection and restores trigger focus. |
| Tab / Shift+Tab | Closes when focus leaves the component, without taking focus back from the next control. |
| Click outside | Closes without selecting; a clicked control keeps focus. |
Examples
Section titled “Examples”Basic usage
Section titled “Basic usage”Without a placeholder or default item, the first item is selected initially.
import { Dropdown } from '@tmedxp/react-components';
const BasicDropdown = () => { return ( <Dropdown label="Powertrain" items={[ { label: 'Hybrid' }, { label: 'Plug-in Hybrid' }, { label: 'Battery Electric' }, ]} /> );};Inside label
Section titled “Inside label”Set labelPosition="inside" to show the label above the selected value or placeholder within the trigger. The label remains visible after selection; initialization and selection behavior are unchanged.
import { Dropdown } from '@tmedxp/react-components';
const DropdownWithInsideLabel = () => { return ( <Dropdown label="Powertrain" labelPosition="inside" placeholder="Select a powertrain" items={[ { label: 'Hybrid' }, { label: 'Plug-in Hybrid' }, { label: 'Battery Electric' }, ]} /> );};With placeholder, helper text and required state
Section titled “With placeholder, helper text and required state”import { Dropdown } from '@tmedxp/react-components';
const DropdownWithPlaceholder = () => { return ( <Dropdown label="Powertrain" placeholder="Select a powertrain" helperText="Choose your preferred powertrain" required items={[ { label: 'Hybrid' }, { label: 'Plug-in Hybrid' }, { label: 'Battery Electric' }, ]} /> );};With a default item
Section titled “With a default item”import { Dropdown } from '@tmedxp/react-components';
const DropdownWithDefaultItem = () => { const items = [ { label: '50 kWh' }, { label: '75 kWh' }, { label: '100 kWh' }, ];
return ( <Dropdown label="Battery capacity" defaultItem={items[1]} items={items} /> );};Responding to selection
Section titled “Responding to selection”Store the selected item for application logic without controlling the dropdown’s internal selection.
import { useState } from 'react';import { Dropdown } from '@tmedxp/react-components';import type { ListItemProperties } from '@tmedxp/react-components';
const DropdownWithSelection = () => { const [selectedItem, setSelectedItem] = useState<ListItemProperties>();
return ( <> <Dropdown label="Powertrain" placeholder="Select a powertrain" items={[ { id: 'hybrid', label: 'Hybrid' }, { id: 'phev', label: 'Plug-in Hybrid' }, { id: 'bev', label: 'Battery Electric' }, ]} onSelect={setSelectedItem} /> <p>Selected powertrain: {selectedItem?.label ?? 'None'}</p> </> );};With disabled options
Section titled “With disabled options”import { Dropdown } from '@tmedxp/react-components';
const DropdownWithDisabled = () => { return ( <Dropdown label="Color" items={[ { label: 'White' }, { label: 'Black', 'aria-disabled': true }, { label: 'Silver' }, { label: 'Blue', 'aria-disabled': true }, ]} /> );};Disabled dropdown
Section titled “Disabled dropdown”import { Dropdown } from '@tmedxp/react-components';
const DisabledDropdown = () => { return ( <Dropdown label="Wheels" disabled items={[{ label: '18"' }, { label: '19"' }, { label: '20"' }]} /> );};Without a visible label
Section titled “Without a visible label”Provide aria-label when omitting the field label.
import { Dropdown } from '@tmedxp/react-components';
const DropdownWithoutLabel = () => { return ( <Dropdown aria-label="Powertrain" placeholder="Select a powertrain" items={[ { label: 'Hybrid' }, { label: 'Plug-in Hybrid' }, { label: 'Battery Electric' }, ]} /> );};Scrollable list
Section titled “Scrollable list”Long lists scroll within the available space without requiring a custom panel height.
import { Dropdown } from '@tmedxp/react-components';
const ScrollableDropdown = () => { return ( <Dropdown label="Options" items={Array.from({ length: 30 }, (_, index) => ({ label: `Option ${index + 1}`, }))} /> );};Updating existing integrations
Section titled “Updating existing integrations”Replace DropdownItemData options using title, value and disabled with ListItemProperties using label, an optional id and aria-disabled. Use defaultItem instead of defaultValue, and handle the full item in onSelect instead of a string in onChange. The activeValue and filled props are no longer supported.
The dropdown follows the WAI-ARIA Listbox pattern — a trigger that opens a single-select list of options — and meets WCAG 2.1 AA. An accessible dropdown keeps that list reachable and operable from the keyboard, keeps assistive technology informed of its open state, and gives every element an accessible name — so the choice it holds is clear whether the user is looking at it, listening to it, or tabbing through it.
For designers
Section titled “For designers”- All list items and states must maintain accessible contrast on every supported surface. Source: WCAG 1.4.3 Contrast (Minimum).
- State must never be conveyed by colour alone — pair it with text, an icon, or a shape. Source: WCAG 1.4.1 Use of Color.
- 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 (e.g.
foreground/neutral/default) rather than fixed values, so the component adapts correctly across themes and surfaces.
For developers
Section titled “For developers”Expose the trigger, list, and options to assistive technology through native list semantics and ARIA. Screen readers announce the count and position of options (“listbox, 3 items, item 1 of 3”) automatically when native list markup is used. To let users type to filter the options, use a searchable dropdown, which is a combobox. The per-element roles, names, and states are in the Labelling elements section below.
Keyboard interaction
Section titled “Keyboard interaction”| Key | Action |
|---|---|
| Enter / Space | Open the dropdown, or select the focused option |
| ↑ / ↓ | Open the dropdown, then move focus between options |
| Home / End | Move focus to the first / last option |
| Escape | Close the dropdown, return focus to the trigger |
| Tab / Shift + Tab | Close the dropdown and move to the next / previous control |
Interactive targets must be at least 44 px high for comfortable touch use — comfortably clearing the WCAG AA minimum. Source: WCAG 2.5.8 Target Size (Minimum).
Focus order
Section titled “Focus order”Opening the list moves focus to the selected option, or to the first option when nothing is selected. Focus reaches only the trigger and, once the list is open, each option in turn — a roving tabindex walks the options while the list container and chevron never receive focus. Selecting an option returns focus to the trigger. The keys that drive this are in the Keyboard interaction table above.
- Hybrid
- Plug-in Hybrid
- Electric
- Trigger
- Option 1
- Option 2
- Option 3
Source: WCAG 2.4.3 Focus Order.
Labelling elements
Section titled “Labelling elements”Give every element the role, name, and state assistive technology needs.
Trigger
aria-haspopup="listbox" with aria-expanded kept in sync with the open state. Name it from a visible label wired with aria-labelledby, or aria-label="Powertrain" when there’s no visible label — never leave the name to the placeholder alone.
Options list
role="listbox" (add aria-multiselectable="true" for checkbox-style dropdowns). Name it with aria-label or aria-labelledby when its purpose isn’t obvious from context, so it doesn’t announce as an unnamed list.
Options
role="option" on each item, with aria-selected="true" on the selected one. Each option takes its accessible name from its text content — keep that text self-describing.
In a checkbox-style dropdown, give every option aria-selected="true" or "false" and make its checkbox inert. The option carries the state and handles the click; the checkbox is only the visual tick, so it is neither focusable nor announced as a second control.
Source: WCAG 4.1.2 Name, Role, Value.