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.

Name	Description	Default
onChange	(value: (string \| number)[]) => void Callback on multiselect value change.
task	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 The `refetchInterval` prop represents how often (in milliseconds) the task query should be rerun to refetch data automatically. The `onSuccess` and `onError` callbacks will run on task success or failure. 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.
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.
width	SizingToken \| "{number}px" Defines the width of the component.	auto
height	SizingToken \| "{number}px" Defines the height of the component.	auto
grow	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.
defaultValue	MultiSelectTValue Initial value of the multiselect.
placeholder	string Text shown when nothing is selected.
autoFocus	boolean Whether to automatically focus on the multiselect input.
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
ItemComponent	ItemComponent The component with which the item is rendered.
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.
outputTransform	(output: TOutput) => (string \| number \| MultiSelectItem)[] Callback to transform the task output.

State API

Name	Description
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

MultiSelect

Basic usage

Task backed

Customizing data

Different label and value

Disabling

Grouping

Component API

State API