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.
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. The data options are automatically inferred from the output of the Task.

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.
outputTransform can also be used to modify the data for customization purposes.

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.

Disabling

The entire multi select can be disabled using defaultDisabled.
Individual options can be disabled by setting disabled: true on the option.

Grouping

Options can be grouped together by specifying the group prop on each option.

Component API

NameDescriptionDefault
onChange
(value: (string | number)[]) => void
Callback on multiselect value change.
validate
((value: (string | number)[]) => string | undefined) | Array<(value: (string | number)[]) => string | undefined>
A single function or an array of functions that validate the input value.
required
boolean
Adds red asterisk on the right side of label and sets required on input element
false
id
string
The ID referenced by the global component state.
size
"xs" | "sm" | "md" | "lg" | "xl"
Select size.
disabled
boolean
Select disabled state. Prefer to use defaultDisabled and component state to disable a multiselect.
loading
boolean
Renders a loading indicator when true.
radius
"xs" | "sm" | "md" | "lg" | "xl"
The border-radius of the multiselect element.
sx
CSSObject
CSS style overrides.
width
number | "content" | "auto" | `${number}%` | `${number}/${number}` | { xs?: ColWidth; sm?: ColWidth; md?: ColWidth; lg?: ColWidth; xl?: ColWidth; }
Width of the component. This component must be a direct child of a <Stack> for this prop to take effect. If an integer is specified, signifies the width in a 12 item grid. 12 means that the component takes up the entire row, 6 is half, 1 is 1/12. If a decimal or fraction is specified, signifies the fractional share of the row. e.g. 1/2 takes up half of the row. If a percentage is specified, signifies the percentage share of the row. e.g. "50%" takes up half of the row. content indicates that the component should take up as much space as its content. auto indicates that the component should take any leftover space on the row. To set width based on the screen size, use an object with a specific width for each breakpoint. e.g. {xs: "100%", md: "50%"} sets the width on xs-md screens to 100% and md and larger screens to 50%.
content
offset
number | `${number}%` | `${number}/${number}` | { xs?: ColOffset; sm?: ColOffset; md?: ColOffset; lg?: ColOffset; xl?: ColOffset; }
Creates a gap to the left of the component. Has the same units as width. This component must be a direct child of a <Stack> for this prop to take effect. If an integer is specified, signifies the offset in a 12 item grid. 6 means the component is offset by half a row, 1 is 1/12 of a row. If a decimal or fraction is specified, signifies the fractional share of the row. e.g. 1/2 offsets a component by half of the row. If a percentage is specified, signifies the percentage share of the row. e.g. "50%" offsets a component by half of the row. To set offset based on the screen size, use an object with a specific offset for each breakpoint. e.g. {xs: "50%", md: "0%"} sets the offset on xs-md screens to 50% and md and larger screens to 0%.
defaultValue
MultiSelectTValue
Initial value of the multiselect.
placeholder
string
Text shown when nothing is selected.
value
MultiSelectTValue
Controlled value of the multiselect. Prefer to use defaultValue and component state.
error
Component
Displays error message after the multiselect input. Can be a string or a React component.
data
(string | number | MultiSelectItem)[]
The data, or options, to display in the multiselect.
label
Component
Multiselect label, displayed before the multiselect input. Can be a string or a React component.
description
Component
Multiselect description, displayed below the multiselect input. Can be a string or a React component.
nothingFound
Component
Nothing found label. Can be a string or a React component.
filter
(value: string, selected: boolean, item: MultiSelectItem) => boolean
Custom function that filters the multiselect options in the dropdown. Defaults to a substring filter.
defaultDisabled
boolean
Initial disabled state of the multiselect.
searchable
boolean
Allows searching when true.
true
clearable
boolean
Allows clearing the selected items when true.
false
initiallyOpened
boolean
Initial dropdown opened state.
false
withinPortal
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.
maxSelectedValues
number
If set, limits the maximum number of selected values.
maxDropdownHeight
number
If set, limits the maximum number of search options to show in the dropdown.
task
string | { slug: string; params?: Record<string, any>; executeOnMount?: boolean; executeOnWindowFocus?: boolean; executeOnReconnect?: boolean; enabled?: boolean; refetchInterval?: number; onSuccess?: (output?: TOutput) => void; onFailure?: (output?: TOutput, error?: TError) => void; }
The task query to execute when this component loads. The component's data will be populated by the task's output. If the task doesn't require any parameters or special options, you can just pass the task slug as a string. Otherwise, create an object with the given params, and set slug to the task slug.
If the task requires parameters, these can be passed in via params.
The executeOnMount, executeOnWindowFocus, and executeOnReconnect params control when the task is (re)run - on component mount, when the window is (re)focused, and if the network reconnects. All of these options are true by default.
The enabled param can be set to false to disable running the task query automatically.
The refetchInterval param represents how often (in milliseconds) the task query should be rerun to refetch data automatically. By default, the task will not automatically refetch data on a millisecond timer (though it may still refetch data on window refocus or network reconnect).
The onSuccess and onFailure callbacks will run on task success or failure. Note that depending on execute or refetch settings, task queries may be run repeatedly, which can trigger these callbacks multiple times.
outputTransform
(output: TOutput) => (string | number | MultiSelectItem)[]
Callback to transform the task output.

State API

NameDescription
value
(string | number)[] | undefined
The selected values
setValue
(value: (string | number)[]) => void
Sets the values of the multi-select.
disabled
boolean
Whether the multi-select is disabled
setDisabled
(disabled?: boolean) => void
Sets the disabled value of the multi-select. If the `disabled` value is not provided, the multi-select will be disabled