Select

A dropdown component allows users to choose a single value from a list of options in a limited space.

Selects (sometimes known as "dropdowns" or "pickers") allow users to choose from a list of options in a limited space. The list of options can change based on the context.

React

released

Vue

released

Elements

released

Android

unsupported

iOS

unsupported

Example

Example theme:

DBA lightFinn lightTori light

Usage

Design Guidelines

See Figma: Warp - Components / Select

Accessibility

If a visible label isn't specified, an aria-label should be provided to the Select for accessibility. If the field is labeled by a separate element, an aria-labelledby prop should be provided using the id of the labeling element instead.

Questions?

Feel free to ask any questions on usage in the Warp DS Slack channel: #nmp-warp-design-system

Frameworks

Import

You can import the component like so:

import { Select } from '@warp-ds/react';

or import it individually to optimize your JS bundle size by adding only the components you need:

import { Select } from '@warp-ds/react/components/select';

Syntax

<Select label="Berries">
  <option value="s">Strawberries</option>
  <option value="r">Raspberries</option>
  <option value="c">Cloudberries</option>
</Select>

Props

Optional Props

name	type	default	notes
id	string		The element's unique identifier. See MDN.
name	string		The name of the input element, used when submitting an HTML form. See MDN.
defaultValue	string & (string|number|readonly string[])		The default value (uncontrolled).
value	string		The current value (controlled).
label	ReactNode		The content to display as the label.
optional	boolean		Mark label to indicate that this select is optional.
hint	ReactNode		The content to display as the hint.
always	boolean		Whether to always show hint.
invalid	boolean		Renders the field in an invalid state. Often paired together with hint to provide feedback about the error.
disabled	boolean		Whether the input is disabled.
readOnly	boolean		Whether the input can be selected but not changed by the user.
required	boolean		Whether user input is required on the input before form submission.
children	ReactNode		The option elements to populate the select with.
className	string		Additional classes to include.
style	CSSProperties		Additional CSS styles for the container.
autoFocus	boolean		Whether the element should receive focus on render.

Value

An initial, uncontrolled, value can be provided using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.

function Example() {
  let [value, setValue] = React.useState('c');

  return (
    <div className="flex flex-col space-y-32">
      <Select label="Berries (uncontrolled)">
        <option value="s">Strawberries</option>
        <option value="r">Raspberries</option>
        <option value="c">Cloudberries</option>
      </Select>

      <Select
        label="Berries (controlled)"
        value={value}
        onChange={(event) => setValue(event.target.value)}
      >
        <option value="s">Strawberries</option>
        <option value="r">Raspberries</option>
        <option value="c">Cloudberries</option>
      </Select>
    </div>
  );
}

Labelling

A visual label should be provided for the Select using the label prop.

Optional

Add the optional prop to indicate that the select is not required.

<Select label="Berries" optional>
  <option value="s">Strawberries</option>
  <option value="r">Raspberries</option>
  <option value="c">Cloudberries</option>
</Select>

Hint text

Selects can provide additional context with hint if the label and placeholder aren't enough. You can force the hint text to always display by setting the always prop.

<Select label="Berries" hint="We'll make jam of your selection" always>
  <option value="s">Strawberries</option>
  <option value="r">Raspberries</option>
  <option value="c">Cloudberries</option>
</Select>

Validation

Selects can communicate to the user whether the current value is invalid. Implement your own validation logic in your app and set the invalid prop to display it as invalid.

invalid is often paired with hint to provide feedback to the user about the error.

<Select label="Berries" invalid hint="The wrong selection gets you berried">
  <option value="s">Strawberries</option>
  <option value="r">Raspberries</option>
  <option value="c">Cloudberries</option>
</Select>

Disabled

Using disabled is considered an anti-pattern and is therefore not supported. There will always be users who don't understand why an element is disabled, or users who can't even see that it is disabled because of poor lighting conditions or other reasons. Please consider more informative alternatives.