v0.29.2

Introduction

Foundations

Layout

Actions & Inputs

Status & Feedback

Utilities

Helpful Links

MultiSelects

MultiSelect are typeable inputs with multiple selectable dropdown items. Selects Design Guidelines.

Edit the code below to see your changes live!

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

  return (
    <Form>
      <FormGroup>
        <MultiSelect
          action={{
            actionType: 'destructive' as 'destructive',
            content: 'Remove Country',
            icon: <DeleteIcon />,
            onActionClick: () => null,
          }}
          filterable={true}
          label="Countries"
          maxHeight={300}
          onOptionsChange={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>
  );
}

function Example() {
  const [value, setValue] = useState(['mx']);
  const handleChange = (val) => setValue(val);
  return (
    <Form>
      <FormGroup>
        <MultiSelect
          action={{
            actionType: 'destructive' as 'destructive',
            content: 'Remove Country',
            icon: <DeleteIcon />,
            onActionClick: () => null,
          }}
          filterable={true}
          label="Countries"
          maxHeight={300}
          onOptionsChange={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>
  );
}

API

MultiSelect

Prop Name	Type	Default	Description
`action`	`SelectAction`		Action option displayed at the end of the list.
`description`	`string \| FormControlDescription`		Append a description to the select field.
`disabled`	`boolean`	`false`	Disables the `MultiSelect` component.
`error`	`string`		Displays a form error around the field.
`filterable`	`boolean`	`true`	Allows you to filter the `SelectOptions` in the `Select`.
`inputRef`	`React.Ref<HTMLInputElement> \| React.RefObject<HTMLInputElement>`		The provided ref will be used for the underlying input element used in the `Select`.
`label`	`string` \| `FormControlLabel`		Adds a label to the field.
`labelId`	`string`		Adds a custom id to the label.
`maxHeight`	`number`	`250`	Sets a `max-height` to the dropdown.
`onOptionsChange` *	`(value: [any], option: [SelectOption]) => void`		Callback called with value of selected option.
`options` *	`Array<SelectOption> \| Array<SelectOptionGroup>`		Accepts an array of `SelectOption` or an array of `SelectOptionGroups`. See example for usage.
`placement`	`auto-start` \| `auto` \| `auto-end` \| `top-start` \| `top` \| `top-end` \| `right-start` \| `right` \| `right-end` \| `bottom-end` \| `bottom` \| `bottom-start` \| `left-end` \| `left` \| `left-start`	`bottom-start`	Determines the location in which the dropdown will be placed.
`positionFixed`	`boolean`	`false`	If set, uses `position: fixed` instead of `position: absolute` to position the items.
`required`	`boolean`		Sets the field as required.
`value`	`[any]`		Modifies the current selected value of the field.

Props ending with * are required

SelectOption

Prop Name	Type	Default	Description
`disabled`	`boolean`	`false`	Sets the `SelectOption` to disabled.'
`content` *	`string`		'Sets the text content of the `SelectOption`.'
`description`	`string`		Sets the content description of the `SelectOption`
`icon`	`Icon`		Pass in an Icon component to display to the left of the text. Only available for single select.
`value` *	`any`		'Stored value of the `SelectOption`.'

Props ending with * are required

SelectAction

Prop Name	Type	Default	Description
`actionType`	`normal` \| `destructive`	`normal`	'Indicates whether the `SelectAction` is of normal or destructive nature.'
`disabled`	`boolean`	`false`	'Sets the `SelectAction` to disabled.'
`content` *	`string`		'Sets the text content of the `SelectAction` .'
`description`	`string`		Sets the content description of the `SelectAction`
`icon`	`Icon`		Pass in an Icon component to display to the left of the text.
`onClick`	`(inputText: string): void`		Returns the current text in the input.

Props ending with * are required

Examples

Position

MultiSelect can be anchored in different directions with the position property. It will automatically find a position if there's not enough space in the chosen direction.

Select

Edit the code below to see your changes live!

<Grid gridColumns="repeat(4, 1fr)">
  <MultiSelect
    label="Select"
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
    ]}
    placeholder="Choose from above"
    placement="top"
    required
  />
  <MultiSelect
    label="Select"
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
    ]}
    placeholder="Choose from below"
    placement="bottom-start"
    required
  />
  <MultiSelect
    label="Select"
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
    ]}
    placeholder="Choose from the right"
    placement="right-start"
    required
  />
  <MultiSelect
    label="Select"
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
    ]}
    placeholder="Choose from the left"
    placement="left-end"
    required
  />
</Grid>

<Grid gridColumns="repeat(4, 1fr)">
  <MultiSelect
    label="Select"
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
    ]}
    placeholder="Choose from above"
    placement="top"
    required
  />
  <MultiSelect
    label="Select"
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
    ]}
    placeholder="Choose from below"
    placement="bottom-start"
    required
  />
  <MultiSelect
    label="Select"
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
    ]}
    placeholder="Choose from the right"
    placement="right-start"
    required
  />
  <MultiSelect
    label="Select"
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
    ]}
    placeholder="Choose from the left"
    placement="left-end"
    required
  />
</Grid>

Max Height

Once the content is longer than the max-height, the Dropdown will be scrollable. It is possible to modify the dimension by passing a maxHeight property.

Select

Edit the code below to see your changes live!

<Grid gridColumns="repeat(3, 1fr)">
  <MultiSelect
    label="Select"
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
      { value: 5, content: 'Option' },
      { value: 6, content: 'Option' },
      { value: 7, content: 'Option' },
      { value: 8, content: 'Option' },
    ]}
    placeholder="Default"
    required
  />
  <MultiSelect
    label="Select"
    maxHeight={150}
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
      { value: 5, content: 'Option' },
      { value: 6, content: 'Option' },
      { value: 7, content: 'Option' },
      { value: 8, content: 'Option' },
    ]}
    placeholder="Smaller"
    required
  />
  <MultiSelect
    label="Select"
    maxHeight={350}
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
      { value: 5, content: 'Option' },
      { value: 6, content: 'Option' },
      { value: 7, content: 'Option' },
      { value: 8, content: 'Option' },
      { value: 9, content: 'Option' },
      { value: 10, content: 'Option' },
      { value: 11, content: 'Option' },
      { value: 12, content: 'Option' },
    ]}
    placeholder="Larger"
    required
  />
</Grid>

<Grid gridColumns="repeat(3, 1fr)">
  <MultiSelect
    label="Select"
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
      { value: 5, content: 'Option' },
      { value: 6, content: 'Option' },
      { value: 7, content: 'Option' },
      { value: 8, content: 'Option' },
    ]}
    placeholder="Default"
    required
  />
  <MultiSelect
    label="Select"
    maxHeight={150}
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
      { value: 5, content: 'Option' },
      { value: 6, content: 'Option' },
      { value: 7, content: 'Option' },
      { value: 8, content: 'Option' },
    ]}
    placeholder="Smaller"
    required
  />
  <MultiSelect
    label="Select"
    maxHeight={350}
    onOptionsChange={() => null}
    options={[
      { value: 1, content: 'Option' },
      { value: 2, content: 'Option' },
      { value: 3, content: 'Option' },
      { value: 4, content: 'Option' },
      { value: 5, content: 'Option' },
      { value: 6, content: 'Option' },
      { value: 7, content: 'Option' },
      { value: 8, content: 'Option' },
      { value: 9, content: 'Option' },
      { value: 10, content: 'Option' },
      { value: 11, content: 'Option' },
      { value: 12, content: 'Option' },
    ]}
    placeholder="Larger"
    required
  />
</Grid>

Disabled

It is possible to disable the entire select component, similar to how you would disable a native HTML select element, by using the disabled property.

Edit the code below to see your changes live!

<Form>
  <FormGroup>
    <MultiSelect
      disabled
      label="Select"
      maxHeight={350}
      onOptionsChange={() => null}
      options={[
        { value: 1, content: 'Option' },
        { value: 2, content: 'Option' },
        { value: 3, content: 'Option' },
        { value: 4, content: 'Option' },
      ]}
      placeholder="Larger"
      required
    />
  </FormGroup>
</Form>

<Form>
  <FormGroup>
    <MultiSelect
      disabled
      label="Select"
      maxHeight={350}
      onOptionsChange={() => null}
      options={[
        { value: 1, content: 'Option' },
        { value: 2, content: 'Option' },
        { value: 3, content: 'Option' },
        { value: 4, content: 'Option' },
      ]}
      placeholder="Larger"
      required
    />
  </FormGroup>
</Form>

Action

Accepts an action object to display at the end of the list.

Edit the code below to see your changes live!

<Form>
  <FormGroup>
    <MultiSelect
      action={{
        actionType: 'destructive',
        content: 'Remove Country',
        icon: <DeleteIcon />,
        onActionClick: () => null,
      }}
      label="Countries"
      onOptionsChange={() => null}
      options={[
        { value: 'us', content: 'United States' },
        { value: 'mx', content: 'Mexico' },
        { value: 'ca', content: 'Canada' },
        { value: 'en', content: 'England' },
      ]}
      placeholder={'Choose country'}
      placement={'bottom-start'}
      required
    />
  </FormGroup>
</Form>

<Form>
  <FormGroup>
    <MultiSelect
      action={{
        actionType: 'destructive',
        content: 'Remove Country',
        icon: <DeleteIcon />,
        onActionClick: () => null,
      }}
      label="Countries"
      onOptionsChange={() => null}
      options={[
        { value: 'us', content: 'United States' },
        { value: 'mx', content: 'Mexico' },
        { value: 'ca', content: 'Canada' },
        { value: 'en', content: 'England' },
      ]}
      placeholder={'Choose country'}
      placement={'bottom-start'}
      required
    />
  </FormGroup>
</Form>

Error

An error prop receives a string to display.

Edit the code below to see your changes live!

<Form>
  <FormGroup>
    <MultiSelect
      label="Countries"
      error="Need to choose a country before proceeding"
      onOptionsChange={() => null}
      options={[
        { value: 'us', content: 'United States' },
        { value: 'mx', content: 'Mexico' },
        { value: 'ca', content: 'Canada' },
        { value: 'en', content: 'England' },
      ]}
      placeholder={'Choose country'}
      placement={'bottom-start'}
      required
    />
  </FormGroup>
</Form>

<Form>
  <FormGroup>
    <MultiSelect
      label="Countries"
      error="Need to choose a country before proceeding"
      onOptionsChange={() => null}
      options={[
        { value: 'us', content: 'United States' },
        { value: 'mx', content: 'Mexico' },
        { value: 'ca', content: 'Canada' },
        { value: 'en', content: 'England' },
      ]}
      placeholder={'Choose country'}
      placement={'bottom-start'}
      required
    />
  </FormGroup>
</Form>

MultiSelect Groups

It is possible to create grouped options with labels with a Select Group by passing label and options to the top-level options property.

Edit the code below to see your changes live!

<Form>
  <FormGroup>
    <MultiSelect
      label="My Options"
      filterable
      onOptionsChange={() => null}
      options={[
        {
          label: 'Group 1',
          options: [
            { value: 'mx', content: 'Mexico' },
            { value: 'ca', content: 'Canada' },
            { value: 'en', content: 'England' },
          ],
        },
        {
          label: 'Group 2',
          options: [
            { value: 'fr', content: 'France' },
            { value: 'gr', content: 'Germany' },
            { value: 'ar', content: 'Argentina' },
          ],
        },
      ]}
    />
  </FormGroup>
</Form>

<Form>
  <FormGroup>
    <MultiSelect
      label="My Options"
      filterable
      onOptionsChange={() => null}
      options={[
        {
          label: 'Group 1',
          options: [
            { value: 'mx', content: 'Mexico' },
            { value: 'ca', content: 'Canada' },
            { value: 'en', content: 'England' },
          ],
        },
        {
          label: 'Group 2',
          options: [
            { value: 'fr', content: 'France' },
            { value: 'gr', content: 'Germany' },
            { value: 'ar', content: 'Argentina' },
          ],
        },
      ]}
    />
  </FormGroup>
</Form>

Option & Action Description

It is possible to add a description for select options and actions.

Edit the code below to see your changes live!

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

  return (
    <Form>
      <FormGroup>
        <MultiSelect
          action={{
            actionType: 'destructive',
            content: 'Remove',
            description: 'Description for remove action',
            icon: <DeleteIcon />,
            onActionClick: () => null,
          }}
          label="Select"
          onOptionsChange={() => null}
          options={[
            { value: 1, content: 'Option #1', description: 'Description for option #1' },
            {
              value: 2,
              content: 'Option #2',
              description: 'Description for option #2',
              disabled: true,
            },
            { value: 3, content: 'Option #3' },
            { value: 4, content: 'Option #4' },
            { value: 5, content: 'Option #5' },
          ]}
          onChange={handleChange}
          placeholder="Choose option"
          required
          value={value}
        />
      </FormGroup>
    </Form>
  );
}

function Example() {
  const [value, setValue] = useState([1]);
  const handleChange = (val) => setValue(val);
  return (
    <Form>
      <FormGroup>
        <MultiSelect
          action={{
            actionType: 'destructive',
            content: 'Remove',
            description: 'Description for remove action',
            icon: <DeleteIcon />,
            onActionClick: () => null,
          }}
          label="Select"
          onOptionsChange={() => null}
          options={[
            { value: 1, content: 'Option #1', description: 'Description for option #1' },
            {
              value: 2,
              content: 'Option #2',
              description: 'Description for option #2',
              disabled: true,
            },
            { value: 3, content: 'Option #3' },
            { value: 4, content: 'Option #4' },
            { value: 5, content: 'Option #5' },
          ]}
          onChange={handleChange}
          placeholder="Choose option"
          required
          value={value}
        />
      </FormGroup>
    </Form>
  );
}

Beta