Select

To add the Select component to your app:

1
2
import { Select } from '@forge/react';

Description

Select allows users to make a single selection or multiple selections from a list of options.

Props

Examples

Appearance

Default

The default select appearance.

1
2
const SelectAppearanceDefault= () => {
  return (
    <Select
      appearance="default"
      options={[
        { label: 'Apple', value: 'a' },
        { label: 'Banana', value: 'b' },
      ]}
    />
  );
}

Subtle

A select that's transparent until interaction or error.

1
2
const SelectAppearanceSubtle= () => {
  return (
    <Select
      appearance="subtle"
      options={[
        { label: 'Apple', value: 'a' },
        { label: 'Banana', value: 'b' },
      ]}
    />
  );
}

Field label and helper message

Always use a label component for each field and associate the label to the field properly. Use the HelperMessage component for any optional field related message.

Required field label

For required fields, always add the RequiredAsterisk component next to the label.

1
2
import { Label, RequiredAsterisk, HelperMessage, Select } from '@forge/react';

const SelectFieldLabel = () => {
  return (
    <>
      <Label labelFor="select">Field label<RequiredAsterisk /></Label>
      <Select
        inputId="select"
        placeholder="Placeholder"
      />
      <HelperMessage>Helper message</HelperMessage>
    </>
  );
}

Spacing

Compact

A select with compact spacing.

1
2
const SelectCompactSpacing = () => {
  return (
    <Select
      inputId="compact-select"
      spacing="compact"
      placeholder="Compact spacing..."
    />
  );
}

States

A select can be in different states such as disabled or invalid.

1
2
const SelectStates = () => {
  return (
    <Stack space="space.200">
      <Select
        isDisabled
        placeholder="Disabled"
      />
      <Select
        isInvalid
        placeholder="Choose a city"
      />
    </Stack>
  );
}

Selection

Single select

Allows the user to select a single item from a dropdown list of options.

1
2
const SelectSingleExample = () => (
  <>
    <Label labelFor="single-select-example">What city do you live in?</Label>
    <Select
      inputId="single-select-example"
      options={[
        { label: 'Adelaide', value: 'adelaide' },
        { label: 'Brisbane', value: 'brisbane' },
        { label: 'Canberra', value: 'canberra' },
        { label: 'Darwin', value: 'darwin' },
        { label: 'Hobart', value: 'hobart' },
        { label: 'Melbourne', value: 'melbourne' },
        { label: 'Perth', value: 'perth' },
        { label: 'Sydney', value: 'sydney' },
      ]}
      placeholder="Choose a city"
    />
  </>
);

Single select clearable

Setting isClearable to true lets users clear their selection using the Backspace or Delete key.

1
2
const SelectSingleClearable = () => (
  <>
    <Label labelFor="single-select-example-clearable">What city do you live in?</Label>
    <Select
      inputId="single-select-example-clearable"
      isClearable={true}
      options={[
        { label: 'Adelaide', value: 'adelaide' },
        { label: 'Brisbane', value: 'brisbane' },
        { label: 'Canberra', value: 'canberra' },
        { label: 'Darwin', value: 'darwin' },
        { label: 'Hobart', value: 'hobart' },
        { label: 'Melbourne', value: 'melbourne' },
        { label: 'Perth', value: 'perth' },
        { label: 'Sydney', value: 'sydney' },
      ]}
      placeholder="Choose a city"
    />
  </>
);

Multi select

Allows the user to select multiple items from a dropdown list of options.

1
2
const SelectMultiExample = () => (
  <>
    <Label labelFor="multi-select-example">What cities have you lived in?</Label>
    <Select
      inputId="multi-select-example"
      options={[
        { label: 'Adelaide', value: 'adelaide' },
        { label: 'Brisbane', value: 'brisbane' },
        { label: 'Canberra', value: 'canberra' },
        { label: 'Darwin', value: 'darwin' },
        { label: 'Hobart', value: 'hobart' },
        { label: 'Melbourne', value: 'melbourne' },
        { label: 'Perth', value: 'perth' },
        { label: 'Sydney', value: 'sydney' },
      ]}
      isMulti
      isSearchable={false}
      placeholder="Choose a city"
    />
  </>
);

Grouped options

Related options can be grouped together in both a single and multi select.

1
2
const SelectGroupedOptionsExample = () => (
  <>
    <Label labelFor="grouped-options-example">What city do you live in?</Label>
    <Select
      inputId="grouped-options-example"
      options={[
        {
          label: 'NSW',
          options: [
            { label: 'Sydney', value: 's' },
            { label: 'Newcastle', value: 'n' },
          ],
        },
        {
          label: 'QLD',options: [
            { label: 'Brisbane', value: 'b' },
            { label: 'Gold coast', value: 'g' },
          ],
        },
        {
          label: 'Other',
          options: [
            { label: 'Canberra', value: 'c' },
            { label: 'Williamsdale', value: 'w' },
            { label: 'Darwin', value: 'd' },
            { label: 'Perth', value: 'p' },
          ],
        },
      ]}
      placeholder="Choose a city"
    />
  </>
);

Accessibility considerations

When using the Select component, we recommend keeping the following accessibility considerations in mind:

• Don’t use placeholder text to clarify field inputs – use the field label and helper text.
• Use a field label to indicate what information goes in the text input. Ensure the label is positioned outside the field so it remains visible at all times.
• Helper text can explain more about what to enter in the text input field. If the text is necessary to understand the field, put it above the text input (below the field label). Always keep this succinct.
• To avoid introducing multiple tab stops per text field, and to reduce keystrokes for assistive technology users, the clear control has been intentionally removed from the tab order. Keyboard users can clear content using the delete key.