WPDS - Select | Components

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.


Open in Playroom

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.


Open in Playroom

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)


Open in Playroom

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.


Open in Playroom

Text overflow

Overflow of the selected value is indicated by an ellipsis


Open in Playroom

Show required


Open in Playroom

Focus


Open in Playroom

Error


Open in Playroom

Success


Open in Playroom

Disabled


Open in Playroom

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
position		enum item-aligned \| popper	----	False
asChild		enum boolean	----	False
side		enum bottom \| left \| right \| top	----	False
sideOffset		number	----	False
align		enum center \| end \| start	----	False
alignOffset		number	----	False
arrowPadding		number	----	False
collisionBoundary		enum Element \| Element[]	----	False
collisionPadding		enum number \| Partial<Record<bottom \| left \| right \| top, number>>	----	False
sticky		enum always \| partial	----	False
hideWhenDetached		enum boolean	----	False
avoidCollisions		enum boolean	----	False
onCloseAutoFocus	Event handler called when auto-focusing on close. Can be prevented.	(event: Event) => void	----	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

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
none		enum boolean \| true	----	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

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
title		string	----	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