Components

Single Select

Design
Code

Let users choose one option from a short popup list.

The single select functions similarly to a radio in that the options are mutually exclusive. Unlike the radio, it’s more space efficient—especially as the number of options (and each option’s length) increases. If the list grows too large, consider a lookup select.

Web
React Native
Android
Apple
Other
uiexpandregionvertical
<SingleSelect
  label="Athlete"
  options={[
    { label: 'Kareem Abdul-Jabbar', value: 'kareem' },
    { label: 'Marv Albert', value: 'marv' },
    { label: 'Al Attles', value: 'al' },
  ]}
  placeholder="Select an athlete"
/>

Props

disabled

bool

Determines whether the select is disabled.

hasError

bool

Determines whether to show an error state (red text and border) on the input.

label

string

The text that appears above the select.

hideLabel

bool

Determines whether to hide the label.

required

bool

Determines whether the required text appears next to the label.

placeholder

string

Placeholder text of the select component when an option isn't selected.

options

array of Options
one OptionGroup

List of options or option groups to be displayed in the menu.

const options = [
  { label: 'Kareem Abdul-Jabbar', value: 'kareem' },
  { label: 'Marv Albert', value: 'marv' },
  { label: 'Al Attles', value: 'al' },
];
const groupOptions = {
  group1: {
    label: 'Offense',
    options: [
      { label: 'Kareem Abdul-Jabbar', value: 'kareem' },
      { label: 'Marv Albert', value: 'marv' },
    ],
  },
  group2: {
    label: 'Defense',
    options: [
      { label: 'Elgin Baylor', value: 'elgin' },
      { label: 'Dave Bing', value: 'dave' },
      ],
  },
};

customOption

func

Renders custom options in the options list of the select. Provided with each option object.

const customOption = {({ optionData }) =>
  <div style={{ display: 'flex', alignItems: 'center' }}>
    <div style={{ paddingRight: '0.5rem' }}>
      <AvatarUser initials={optionData.initials} />
    </div>

    <div>
      <OptionTitle>
        {optionData.label}
      </OptionTitle>

      <OptionSubtitle>
        {optionData.description}
      </OptionSubtitle>
    </div>
  </div>
}

maxHeight

string
number

A string indicating the max height of the menu represented as a CSS value, e.g., 100px, 5rem.

helpText

string

The text that appears below the select, usually instructing the user on what to provide.

id

string

Id string that applies to most child elements.

name

string

Assigned to the hidden input's name attribute if the select is used as an uncontrolled component.

value

object
number
string

The value (option) selected.

defaultValue

object
number
string

The value (option) that is initially displayed on page load.

qaId

string

A unique string that appears as a data attribute in the rendered code, serving as a hook for automated tests.

onChange

func

Responds to the select value changing. The corresponding object of the selected option is passed.

onMenuOpen

func

Responds when the select opens.

Notes

  • This can act as a controlled or uncontrolled component.
    • When a value prop is provided, it should show the currently selected value managed by an external state. That state is managed by the onChange prop.
    • If used as an uncontrolled component, a hidden input is rendered, set to the selected item's value. The hidden input's name attribute is set to the name prop provided.
  • To show an error message, simply pass in hasError and put the error text in the helpText attribute.