Anatomy
- Selected value
- Label/placeholder
- Helper text (optional)
- Chevron icon (actionable)
- Border
- Check icon (indicates selected option)
- Options list
- Option hover state
- Option
Options
No styling options
The select component currently only supports one size and variant.
Behavior
Options list (Active)
Clicking or tapping the select field initiates the active state, revealing an options list that consists of a set of values. When in the active state, the label/placeholder is reduced in size and the chevron icon rotates 180 degrees, pointing upwards.
The options list may contain as many values as needed and becomes scrollable if there are more options than what is currently in view.
Making a selection (Active)
The options list can be navigated by mouse hover or via the up/down arrow keys (indicated by a faint highlight). clicking or tapping an option in the list will select the chosen value (indicated by the check icon)
Once a selection is made, the chosen value is displayed within the select field and the options list is automatically dismissed. Selection can also be achieved by pressing the Enter/Return key while an option is highlighted. to cancel selection/dismiss the options list, click or tap outside the element or press the Esc key.
Select groups
The options list can be segmented into groups. Grouping options within a select field can be helpful for creating categories or subcategories of similar items.
Text overflow
Overflow of the selected value is indicated by an ellipsis
Show required
Focus
Error
Success
Disabled
Accessibility
ARIA
Assistive technologies (e.g. screen readers) announce the element clearly to users, including its role, name and state.
Accessibility
The listbox position is adjusted (i.e. does not get cut off the screen).
API Reference
SelectRoot
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| children | Used to insert select elements into the root component | enum ReactNode | ---- | False |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
| disabled | The underlying input element disabled attribute | enum boolean | ---- | False |
| error | Indicates there is an error | enum boolean | ---- | False |
| errorMessage | Text displayed below the select to describe the cause of the error | enum ReactNode | ---- | False |
| helperText | Text displayed below the input to provide additional context | enum ReactNode | ---- | False |
| onValueChange | Event handler called when the value changes. | enum ((value: string) => void) | ((state: string) => void) | ---- | False |
| required | The select element's required attribute | enum boolean | ---- | False |
| success | Indicates there is a success | enum boolean | ---- | False |
| value | The controlled value of the select. Should be used in conjunction with onValueChange | string | ---- | False |
| defaultValue | The value of the select when initially rendered. Use when you do not need to control the state of the select. | string | ---- | False |
| open | force overlay open | enum boolean | ---- | False |
SelectContent
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| children | Used to insert select elements into the root component | enum ReactNode | ---- | False |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; } | ---- | False |
| asChild | enum boolean | ---- | False | |
| onEscapeKeyDown | Event handler called when the escape key is down. Can be prevented. | (event: KeyboardEvent) => void | ---- | False |
| onPointerDownOutside | Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. | (event: PointerDownOutsideEvent) => void | ---- | False |
| onCloseAutoFocus | Event handler called when auto-focusing on close. Can be prevented. | (event: Event) => void | ---- | False |
SelectGroup
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| children | Used to insert select elements into the root component | enum ReactNode | ---- | False |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; } | ---- | False |
| label | The value of the select when initially rendered. Use when you do not need to control the state of the select. | string | ---- | False |
| none | enum boolean | true | ---- | False |
SelectItem
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| children | Used to insert select elements into the root component | enum ReactNode | ---- | False |
| disabled | enum boolean | ---- | False | |
| value | The value associated with this item | string | ---- | True |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | {} & { alignContent?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; } | ---- | False |
| asChild | enum boolean | ---- | False | |
| textValue | string | ---- | False |
SelectLabel
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| isFloating | enum boolean | true | ---- | False | |
| isDisabled | enum boolean | true | ---- | False | |
| children | Used to insert select elements into the root component | enum ReactNode | ---- | False |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
SelectTrigger
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| children | Used to insert select elements into the root component | enum ReactNode | ---- | False |
| asChild | enum boolean | ---- | False | |
| success | enum boolean | true | ---- | False | |
| error | enum boolean | true | ---- | False | |
| isInvalid | enum boolean | true | ---- | False | |
| isDisabled | enum boolean | true | ---- | False | |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |
SelectValue
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| isDisabled | enum boolean | true | ---- | False | |
| placeholder | enum ReactNode & string | ---- | False | |
| children | Used to insert select elements into the root component | enum ReactNode | ---- | False |
| asChild | enum boolean | ---- | False | |
| css | WPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides. | CSS | ---- | False |