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).