Skip to main content
Design system

Select

A select is a type of form element that provides a method for choosing one item from a list of options.

Bundle size: 10.73 kB
Install: 
npm install @washingtonpost/wpds-ui-kit
|Copy
Usage: 
import { Select } from "@washingtonpost/wpds-ui-kit"
|Copy
Storybook:  View on Storybook
Source:  View on Github

Table of Contents

Anatomy

  1. Selected value
  2. Label/placeholder
  3. Helper text (optional)
  4. Chevron icon (actionable)
  5. Border
  6. Check icon (indicates selected option)
  7. Options list
  8. Option hover state
  9. 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

PropDescriptionTypeDefaultRequired
childrenUsed to insert select elements into the root component
ReactNode
----False
cssWPDS 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
disabledThe underlying input element disabled attribute
boolean
----False
errorIndicates there is an error
boolean
----False
errorMessageText displayed below the select to describe the cause of the error
ReactNode
----False
helperTextText displayed below the input to provide additional context
ReactNode
----False
onValueChangeEvent handler called when the value changes.
((value: string) => void) | ((state: string) => void)
----False
requiredThe select element's required attribute
boolean
----False
successIndicates there is a success
boolean
----False
valueThe controlled value of the select. Should be used in conjunction with onValueChange
string
----False
defaultValueThe value of the select when initially rendered. Use when you do not need to control the state of the select.
string
----False
openforce overlay open
boolean
----False

SelectTrigger

PropDescriptionTypeDefaultRequired
childrenUsed to insert select elements into the root component
ReactNode
----False
asChild
boolean
----False
success
boolean | "true" | ({ "@initial"?: boolean | "true"; "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; ... 17 more ...; "@light"?: boolean | "true"; } & { ...; })
----False
error
boolean | "true" | ({ "@initial"?: boolean | "true"; "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; ... 17 more ...; "@light"?: boolean | "true"; } & { ...; })
----False
isInvalid
boolean | "true" | ({ "@initial"?: boolean | "true"; "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; ... 17 more ...; "@light"?: boolean | "true"; } & { ...; })
----False
isDisabled
boolean | "true" | ({ "@initial"?: boolean | "true"; "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; ... 17 more ...; "@light"?: boolean | "true"; } & { ...; })
----False
cssWPDS 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

SelectLabel

PropDescriptionTypeDefaultRequired
isFloating
boolean | "true" | ({ "@initial"?: boolean | "true"; "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; ... 17 more ...; "@light"?: boolean | "true"; } & { ...; })
----False
isDisabled
boolean | "true" | ({ "@initial"?: boolean | "true"; "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; ... 17 more ...; "@light"?: boolean | "true"; } & { ...; })
----False
childrenUsed to insert select elements into the root component
ReactNode
----False
cssWPDS 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

SelectValue

PropDescriptionTypeDefaultRequired
isDisabled
boolean | "true" | ({ "@initial"?: boolean | "true"; "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; ... 17 more ...; "@light"?: boolean | "true"; } & { ...; })
----False
placeholder
ReactNode & string
----False
childrenUsed to insert select elements into the root component
ReactNode
----False
asChild
boolean
----False
cssWPDS 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

SelectContent

PropDescriptionTypeDefaultRequired
childrenUsed to insert select elements into the root component
ReactNode
----False
cssWPDS 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?: AlignContent | ScaleValue | Globals | Index; alignItems?: AlignItems | ScaleValue | Globals | Index; ... 426 more ...; vectorEffect?: VectorEffect | ... 2 more ... | Index; } & ... 7 more ... & { ...; }
----False
position
"item-aligned" | "popper"
----False
sticky
"always" | "partial"
----False
asChild
boolean
----False
side
"bottom" | "left" | "right" | "top"
----False
sideOffset
number
----False
align
"center" | "end" | "start"
----False
alignOffset
number
----False
arrowPadding
number
----False
collisionBoundary
Element | Element[]
----False
collisionPadding
number | Partial<Record<"bottom" | "left" | "right" | "top", number>>
----False
hideWhenDetached
boolean
----False
avoidCollisions
boolean
----False
onCloseAutoFocusEvent handler called when auto-focusing on close. Can be prevented.
(event: Event) => void
----False
onEscapeKeyDownEvent handler called when the escape key is down. Can be prevented.
(event: KeyboardEvent) => void
----False
onPointerDownOutsideEvent handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented.
(event: PointerDownOutsideEvent) => void
----False

SelectItem

PropDescriptionTypeDefaultRequired
childrenUsed to insert select elements into the root component
ReactNode
----False
disabled
boolean
----False
valueThe value associated with this item
string
----
True
cssWPDS 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?: AlignContent | ScaleValue | Globals | Index; alignItems?: AlignItems | ScaleValue | Globals | Index; ... 426 more ...; vectorEffect?: VectorEffect | ... 2 more ... | Index; } & ... 7 more ... & { ...; }
----False
asChild
boolean
----False
textValue
string
----False

SelectGroup

PropDescriptionTypeDefaultRequired
childrenUsed to insert select elements into the root component
ReactNode
----False
cssWPDS 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?: AlignContent | ScaleValue | Globals | Index; alignItems?: AlignItems | ScaleValue | Globals | Index; ... 426 more ...; vectorEffect?: VectorEffect | ... 2 more ... | Index; } & ... 7 more ... & { ...; }
----False
none
boolean | "true" | ({ "@initial"?: boolean | "true"; "@sm"?: boolean | "true"; "@md"?: boolean | "true"; "@lg"?: boolean | "true"; "@xl"?: boolean | "true"; "@xxl"?: boolean | "true"; "@notSm"?: boolean | "true"; ... 17 more ...; "@light"?: boolean | "true"; } & { ...; })
----False
labelThe value of the select when initially rendered. Use when you do not need to control the state of the select.
string
----False
Edit this page on GitHub.
CommunityXTwittergithubGithubyoutubeYoutube