Select

Overview

Select gives merchants the ability to make a single selection or multiple selections from a list of options.

When to use:

  • When a user needs to make selections in a form.

Implementation

Selects are typeable inputs with selectable options.

Edit the code below to see your changes live!

function Example() {
  const [value, setValue] = useState('mx');
  const handleChange = (val) => setValue(val);

  return (
    <Form>
      <FormGroup>
        <Select
          action={{
            actionType: 'destructive' as const,
            content: 'Remove Country',
            icon: <DeleteIcon />,
            onActionClick: () => null,
          }}
          filterable={true}
          label="Countries"
          maxHeight={300}
          onOptionChange={handleChange}
          options={[
            { value: 'us', content: 'United States' },
            { value: 'mx', content: 'Mexico' },
            { value: 'ca', content: 'Canada' },
            { value: 'en', content: 'England' },
            { value: 'fr', content: 'France' },
            { value: 'gr', content: 'Germany' },
            { value: 'ar', content: 'Argentina' },
            { value: 'ru', content: 'Russia', disabled: true },
            { value: 'ch', content: 'Chile' },
            { value: 'bo', content: 'Bolivia' },
            { value: 'jp', content: 'Japan' },
            { value: 'cn', content: 'China' },
            { value: 'sk', content: 'South Korea' },
            { value: 'au', content: 'Australia' },
            { value: 'ug', content: 'Uganda' },
          ]}
          placeholder="Choose country"
          placement="bottom-start"
          required
          value={value}
        />
      </FormGroup>
    </Form>
  );
}

Props

Prop name
Type
Default
Description
actionSelectAction

Action option displayed at the end of the list.

autoCompletestringoff

Set the autoComplete property for the input.

descriptionstring | FormControlDescription

Append a description to the select field.

disabledbooleanfalse

Disables the Select component.

errorstring

Displays a form error around the field.

filterablebooleantrue

Allows you to filter the SelectOptions in the Select.

inputRefReact.Ref<HTMLInputElement> | React.RefObject<HTMLInputElement>

The provided ref will be used for the underlying input element used in the Select.

labelstring | FormControlLabel

Adds a label to the field.

labelIdstring

Adds a custom id to the label.

maxHeightnumber250

Sets a max-height to the dropdown.

onClose() => void

Function that will be called when the Select is closed.

onOpen() => void

Function that will be called when the Select is opened.

onOptionChange *(value: any, option: SelectOption) => void

Callback called with value of selected option.

options *Array<SelectOption> | Array<SelectOptionGroup>

Accepts an array of SelectOptions or an array of SelectOptionGroups. See implementation section for usage.

placementauto-start | auto | auto-end | top-start | top | top-end | right-start | right | right-end | bottom-end | bottom | bottom-start | left-end | left | left-startbottom-start

Determines the location in which the dropdown will be placed.

positionFixedbooleanfalse

If set, uses position: fixed instead of position: absolute to position the list.

requiredboolean

Sets the field as required.

valueany

Modifies the current selected value of the field.

localization{ optional: string }

Overrides the label with localized text.

Props ending with * are required

Do's and Don'ts

Do
Use within Panels.
Create all select options within a container.
Use for a single selection between 4 or more pre-defined options.
Default a selection if possible.
Add placeholder text if additional context is needed.
Logically group select options when it makes sense.
Don't
Don’t use Select component when user needs to make more than one selection (see MultiSelect).
In most cases avoid using long labels (ideally less than three words).