React
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.