v1.0.13

Select

Stable

This component is considered stable. Reach out to the Spark team to find out more about what this means.

Open in Storybook Edit this page

Installation

Install yarn add @spark-web/select

npm @spark-web/select

Source GitHub.com

Bundle unpkg.com

Allows the user to make a single selection from a list of values — usually in a form. If only a few options are provided, consider using a RadioButton instead.

Usage

Field

Each select input must be accompanied by a Field with a label. Effective form labeling helps inform users which selection to make.

Examples

Controlled

A <Select> can be both controlled and uncontrolled. To control a <Select> provide a value, as well as an onChange function to set the new value when the select is updated.

State

Open in Playroom

const [selectedOption, setSelectedOption] = React.useState('');

const options = [
  { label: 'NSW', value: 'nsw' },
  { label: 'VIC', value: 'vic' },
  { label: 'QLD', value: 'qld' },
  { label: 'SA', value: 'sa' },
  { label: 'WA', value: 'wa' },
  { label: 'TAS', value: 'tas' },
  { label: 'NT', value: 'nt' },
  { label: 'ACT', value: 'act' },
];

return (
  <Stack gap="large">
    <Field label="State">
      <Select
        placeholder="Choose a state..."
        value={selectedOption}
        onChange={event => setSelectedOption(event.target.value)}
        options={options}
        required
      />
    </Field>
    {selectedOption && (
      <Text>
        You have selected{' '}
        {options.find(option => option.value === selectedOption).label}
      </Text>
    )}
  </Stack>
);

const [selectedOption, setSelectedOption] = React.useState('');

const options = [
  { label: 'NSW', value: 'nsw' },
  { label: 'VIC', value: 'vic' },
  { label: 'QLD', value: 'qld' },
  { label: 'SA', value: 'sa' },
  { label: 'WA', value: 'wa' },
  { label: 'TAS', value: 'tas' },
  { label: 'NT', value: 'nt' },
  { label: 'ACT', value: 'act' },
];

return (
  <Stack gap="large">
    <Field label="State">
      <Select
        placeholder="Choose a state..."
        value={selectedOption}
        onChange={event => setSelectedOption(event.target.value)}
        options={options}
        required
      />
    </Field>
    {selectedOption && (
      <Text>
        You have selected{' '}
        {options.find(option => option.value === selectedOption).label}
      </Text>
    )}
  </Stack>
);

Uncontrolled

The <Select>, by default, is an uncontrolled component, meaning that the form data is controlled directly by the DOM itself. To access the value, instead of writing an onChange handler, you would use a ref to get form values from the DOM.

Breaking Bad Characters

Open in Playroom

<Field label="Breaking Bad Characters">
  <Select
    options={[
      { label: 'Walter White', value: 'walter-white' },
      { label: 'Jesse Pinkman', value: 'jesse-pinkman' },
      { label: 'Saul Goodman', value: 'saul-goodman' },
      { label: 'Gus Fring', value: 'gus-fring' },
      { label: 'Hank Schrader', value: 'hank-schrader' },
      { label: 'Mike Ehrmantraut', value: 'mike-ehrmantraut' },
    ]}
  />
</Field>

<Field label="Breaking Bad Characters">
  <Select
    options={[
      { label: 'Walter White', value: 'walter-white' },
      { label: 'Jesse Pinkman', value: 'jesse-pinkman' },
      { label: 'Saul Goodman', value: 'saul-goodman' },
      { label: 'Gus Fring', value: 'gus-fring' },
      { label: 'Hank Schrader', value: 'hank-schrader' },
      { label: 'Mike Ehrmantraut', value: 'mike-ehrmantraut' },
    ]}
  />
</Field>

Groups

Related options can be grouped by passing in an array of objects with a label and option key — where each option is an array of objects with label, value and (optionally) disabled keys. Internally this uses the <optgroup> element.

Select

Open in Playroom

const [selectedOption, setSelectedOption] = React.useState('');

return (
  <Field label="Select">
    <Select
      placeholder="TV Characters"
      options={[
        {
          label: 'Mad Men',
          options: [
            { label: 'Don Draper', value: 'don-draper' },
            { label: 'Peggy Olson', value: 'peggy-olson' },
            { label: 'Joan Harris', value: 'joan-harris' },
            { label: 'Roger Sterling', value: 'roger-sterling' },
            { label: 'Pete Campbell', value: 'pete-campbell' },
          ],
        },
        {
          label: 'Breaking Bad',
          options: [
            { label: 'Walter White', value: 'walter-white' },
            { label: 'Jesse Pinkman', value: 'jesse-pinkman' },
            { label: 'Saul Goodman', value: 'saul-goodman' },
            { label: 'Gus Fring', value: 'gus-fring' },
            { label: 'Hank Schrader', value: 'hank-schrader' },
            { label: 'Mike Ehrmantraut', value: 'mike-ehrmantraut' },
          ],
        },
      ]}
    />
  </Field>
);

const [selectedOption, setSelectedOption] = React.useState('');

return (
  <Field label="Select">
    <Select
      placeholder="TV Characters"
      options={[
        {
          label: 'Mad Men',
          options: [
            { label: 'Don Draper', value: 'don-draper' },
            { label: 'Peggy Olson', value: 'peggy-olson' },
            { label: 'Joan Harris', value: 'joan-harris' },
            { label: 'Roger Sterling', value: 'roger-sterling' },
            { label: 'Pete Campbell', value: 'pete-campbell' },
          ],
        },
        {
          label: 'Breaking Bad',
          options: [
            { label: 'Walter White', value: 'walter-white' },
            { label: 'Jesse Pinkman', value: 'jesse-pinkman' },
            { label: 'Saul Goodman', value: 'saul-goodman' },
            { label: 'Gus Fring', value: 'gus-fring' },
            { label: 'Hank Schrader', value: 'hank-schrader' },
            { label: 'Mike Ehrmantraut', value: 'mike-ehrmantraut' },
          ],
        },
      ]}
    />
  </Field>
);

Props

Prop	Type	Description
options	OptionsOrGroups	The values that can be selected by the input.
data?	DataAttributeMap	Sets data attributes for the element.
placeholder?	string	Placeholder text for when the input does not have an initial value.