MultiSelect

The MultiSelect component allows user to search for and pick multiple options from the given data.

Basic usage
The multi select must have a set of data options that the user can choose from.
tsx
Copied
1
<MultiSelect id="selectCats" data={["Cat1", "Cat2", "Cat3"]} placeholder="Select cats" />
data can be a list of strings, numbers, or MultiSelectItems.
A MultiSelectItem has the form { value: string | number, label?: string, group?: string, disabled?: boolean }. Use this when you want to have a different label and value, when you want to group elements, or when you want to disable individual options.

Task backed
A multi select can be backed by an Airplane Task rather than hardcoding the data. Set the task prop to call an Airplane task. As long as the task output matches the type of data, the data options are automatically inferred from the output.
tsx
Copied
1
<MultiSelect id="selectCats" task="list_cat_breeds" placeholder="Select cats" />

Customizing data
To use a task that outputs a format that isn't expected by the multi select, use outputTransform to convert the output. This prop is a function that receives the multi select data and returns new data. For example, a SQL task may return two columns, name and breed. If we want to build a multi select component that allows the user to select from just the name column, we can do the following.
tsx
Copied
1
<MultiSelect
2
  id="selectCats"
3
  task="list_cats_sql"
4
  outputTransform={(v) => v.Q1.map((cat) => cat.name)}
5
  placeholder="Select cats"
6
/>
outputTransform can also be used to modify the data for customization purposes, perhaps to capitalize the cat breed's name as the label but keep the original name as the value.
tsx
Copied
1
<MultiSelect
2
  id="selectCats"
3
  task="list_cat_breeds"
4
  placeholder="Select cat breeds"
5
  outputTransform={(catBreeds) =>
6
    catBreeds.map((breed) => ({ label: breed.toUpperCase(), value: breed }))
7
  }
8
/>

Different label and value
Each option's label (the user-facing value) and value (the backing value) can differ by using an object with keys value and label instead of a string.
tsx
Copied
1
<MultiSelect
2
  id="selectCats"
3
  data={[
4
    { label: "Bootz", value: "Cat1" },
5
    { label: "Hazel", value: "Cat2" },
6
    { label: "Baosky", value: "Cat3" },
7
  ]}
8
  placeholder="Select cats"
9
/>

Disabling
The entire multi select can be disabled using defaultDisabled.
tsx
Copied
1
<MultiSelect
2
  id="selectCats"
3
  data={["Cat1", "Cat2", "Cat3"]}
4
  placeholder="Select cats"
5
  defaultDisabled
6
/>
Individual options can be disabled by setting disabled: true on the option.
tsx
Copied
1
<MultiSelect
2
  id="selectCats"
3
  data={[
4
    { label: "Bootz", value: "Cat1", disabled: true },
5
    { label: "Hazel", value: "Cat2" },
6
    { label: "Baosky", value: "Cat3", disabled: true },
7
  ]}
8
  placeholder="Select cats"
9
/>

Grouping
Options can be grouped together by specifying the group prop on each option.
tsx
Copied
1
<MultiSelect
2
  data={[
3
    { value: "Bootz", label: "Bootz", group: "Cat" },
4
    { value: "Hazel", label: "Hazel", group: "Cat" },
5
    { value: "Max", label: "Max", group: "Dog" },
6
  ]}
7
  placeholder="Select pets"
8
/>

Component API
autoFocus
optional
boolean

Whether to automatically focus on the multiselect input.

clearable
optional
Default
false
boolean

Allows clearing the selected items when true.

data
optional
(string | number | MultiSelectItem)[]

The data, or options, to display in the multiselect.

defaultDisabled
optional
boolean

Initial disabled state of the multiselect.

defaultValue
optional
MultiSelectTValue

Initial value of the multiselect.

description
optional
Component

Multiselect description, displayed below the multiselect input. Can be a string or a React component.

disabled
optional
boolean

Select disabled state. Prefer to use defaultDisabled and component state to disable a multiselect.

error
optional
Component

Displays error message after the multiselect input. Can be a string or a React component.

filter
optional
(value: string, selected: boolean, item: MultiSelectItem) => boolean

Custom function that filters the multiselect options in the dropdown. Defaults to a substring filter.

grow
optional
boolean

If true, the element will grow to fill available space.

This prop works only if the element is a direct child of a Stack.

height
optional
Default
auto
SizingToken | "{number}px"
Defines the height of the component. See SizingToken docs for more details.
id
optional
string

The ID referenced by the global component state.

initiallyOpened
optional
Default
false
boolean

Initial dropdown opened state.

ItemComponent
optional
ItemComponent

The component with which the item is rendered.

label
optional
Component

Multiselect label, displayed before the multiselect input. Can be a string or a React component.

loading
optional
boolean

Renders a loading indicator when true.

maxDropdownHeight
optional
number

If set, limits the maximum number of search options to show in the dropdown.

maxSelectedValues
optional
number

If set, limits the maximum number of selected values.

nothingFound
optional
Component

Nothing found label. Can be a string or a React component.

onChange
optional
(value: (string | number)[]) => void

Callback on multiselect value change.

outputTransform
optional
(output: TOutput) => (string | number | MultiSelectItem)[]

Callback to transform the task output.

placeholder
optional
string

Text shown when nothing is selected.

radius
optional
"xs" | "sm" | "md" | "lg" | "xl"

The border-radius of the multiselect element.

required
optional
Default
false
boolean

Adds red asterisk on the right side of label and sets required on input element

searchable
optional
Default
true
boolean

Allows searching when true.

size
optional
"xs" | "sm" | "md" | "lg" | "xl"

Select size.

task
optional
string | AirplaneFunc | SlugQuery | FunctionQuery

The task query to execute when this component loads. The component's data will be populated by the task's output and loading and error states will be handled automatically.

If the task doesn't require any parameters or special options, you can just pass the task slug (task="my_task") or an AirplaneFunc—the return value of airplane.task() (task={myTask}).

If the task does require parameters or special options, pass the task as an object. If you are using a slug, specify the slug prop to pass the task configuration as a SlugQuery. If you are using an AirplaneFunc, specify the fn prop to pass the task configuration as a FunctionQuery.

SlugQuery
FunctionQuery
validate
optional
((value: (string | number)[]) => string | undefined) | Array<(value: (string | number)[]) => string | undefined>

A single function or an array of functions that validate the input value.

value
optional
MultiSelectTValue

Controlled value of the multiselect. Prefer to use defaultValue and component state.

width
optional
Default
auto
SizingToken | "{number}px"
Defines the width of the component. See SizingToken docs for more details.
withinPortal
optional
boolean

If true, the multiselect dropdown is rendered in a React portal. Use this if the multiselect is in a table or dialog and is cut off by its parent container.

State API
disabled
optional
boolean

Whether the multi-select is disabled

setDisabled
optional
(disabled?: boolean) => void

Sets the disabled value of the multi-select. If the disabled value is not provided, the multi-select will be disabled

setValue
optional
(value: (string | number)[]) => void

Sets the values of the multi-select.

value
optional
(string | number)[] | undefined

The selected values

PrivacyTermsSupport