Skip to content

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.

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

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.

  • Supplying placeholder, including an empty string, starts with no selected item and takes precedence over defaultItem.
  • 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 defaultItem or items after 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 onSelect once with that item. Initial selection does not call onSelect.

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.

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.

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.

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' },
]}
/>
);
};

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' },
]}
/>
);
};
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} />
);
};

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>
</>
);
};
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 },
]}
/>
);
};
import { Dropdown } from '@tmedxp/react-components';
const DisabledDropdown = () => {
return (
<Dropdown
label="Wheels"
disabled
items={[{ label: '18"' }, { label: '19"' }, { label: '20"' }]}
/>
);
};

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' },
]}
/>
);
};

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}`,
}))}
/>
);
};

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.