① Label
Visible label — required for accessibility
② Leading icon
Optional 16×16px contextual icon
③ Trigger
Shows selected value or placeholder
④ Chevron
Rotates 180° when open
Examples
Interactive dropdowns with keyboard navigation, option highlighting, and accessible error states.
Default select
A labelled dropdown with a list of options. Clicking an option closes the menu and updates the trigger label.
Sizes
sm (32px) for compact contexts like filter bars; md (40px) for standard forms.
With leading icon
Icons provide visual context about the type of selection being made.
With helper text
Persistent guidance for when the user needs context before selecting.
Shipping rates and availability vary by region.
With a default value
Pass a defaultValue matching one of the option values to pre-select an option.
Error state
Red border, red focus ring, and an inline message. Trigger after validation, not on first render.
Please select a shipping region to continue.
Disabled state
Muted background and greyed text — use when the field is unavailable in the current context.
Currency is set at the organisation level.
Form example
Selects alongside inputs — full-width in a typical form layout.
States
Select an option
Select an option
Select an option
Australia
Select an option
Select an option
Anatomy
③ Placeholder
Option A
Option B
Design tokens
| Token | Value | Description |
|---|---|---|
input/background/default | #ffffff | Trigger background |
input/background/disabled | #e1e1e1 | Disabled background |
input/border/Default | #cccccc | Default border |
input/border/hover | #a3a3a3 | Hover border |
input/border/focus | #318272 | Open/focus border |
input/border/error | #bc1700 | Error border |
input/border/disabled | #e1e1e1 | Disabled border |
input/text/placeholder | #8f8f8f | Placeholder colour |
input/text/value | #3b3b3d | Selected value colour |
focus/Ring | #acffef | Focus ring shadow colour |
background/brand/subtle | #f3fffc | Selected option highlight |
Radius/sm | 4px | Trigger corner radius |
Radius/md | 8px | Dropdown corner radius |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
options | { value: string; label: string }[] | — | Array of selectable options. |
label | string | — | Visible label above the trigger. |
placeholder | string | "Select…" | Text shown when no option is selected. |
defaultValue | string | — | Pre-selected option value on first render. |
size | "sm" | "md" | "md" | sm=32px · md=40px trigger height. |
disabled | boolean | false | Prevents opening the dropdown. |
leadingIcon | React.ElementType | — | Icon inside the trigger, before the label. |
errorMessage | string | — | Activates error state and shows this message. |
helperText | string | — | Persistent helper text — hidden when errorMessage is set. |
fullWidth | boolean | false | Stretches to fill parent container. |
onChange | (value: string) => void | — | Callback when the selected value changes. |
Content guidelines
Do
- Use a meaningful placeholder like "Select a category"
- Sort options logically (alphabetical, most-used first)
- Pre-select a sensible default when one exists
- Use for 4+ options — use radio buttons for 2–3
- Keep option labels short and scannable
Don't
- ✕Use "Choose one…" as a placeholder for required fields
- ✕Use a select for fewer than 4 options
- ✕Nest options more than one level deep
- ✕Disable the select without explaining why
- ✕Use for actions — use a menu or button instead