Select

Searchable select dropdown
Select component allows user to pick one option from the given data

Basic usage

The Select component must have a set of data options that the user can choose from.
Loading view...
data can be a list of strings, numbers, or SelectItems.
A SelectItem 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 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.
Loading view...

Customizing data

The data options of a task backed Select can be transformed with the outputTransform prop. This prop is a function that receives the Select data and returns new data.
Loading view...

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.
Loading view...

Disabling

The entire Select can be disabled using defaultDisabled.
Loading view...
Individual options can be disabled by setting disabled: true on the option.
Loading view...

Grouping

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

Component API

NameDescriptionDefault
onChange
(value: string | number | null) => void
Callback on select value change
validate
((value: string | number | null) => string | undefined) | Array<(value: string | number | null) => 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 Adds red asterisk on the right side of label Sets required on input element
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 select.
loading
boolean
Renders a loading indicator when true
radius
"xs" | "sm" | "md" | "lg" | "xl"
The border-radius of the select 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
string | number
Initial value of the select
placeholder
string
Text shown when nothing is selected.
value
string | number
Controlled value of the select. Prefer to use defaultValue and component state.
error
Component
Displays error message after the select input. Can be a string or a React component
data
(string | number | SelectItem)[]
The data, or options, to display in the select
label
Component
Select label, displayed before the select input. Can be a string or a React component.
description
Component
Select description, displayed below the select 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, item: SelectItem) => boolean
Custom function that filters the select options in the dropdown. Defaults to a substring filter.
defaultDisabled
boolean
Initial disabled state of the select
searchable
boolean
Allows searching when true
true
clearable
boolean
Allows clearing the selected item when true
allowDeselect
boolean
Allow deselecting items on click
initiallyOpened
boolean
Initial dropdown opened state
itemComponent
ItemComponent
The component with which the item is rendered
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 | SelectItem)[]
Callback to transform the task output

State API

NameDescription
value
TValue | undefined
The selected value
setValue
(value: TValue | undefined) => void
Sets the value of the select. Set the value as `undefined` to clear the selection
disabled
boolean
Whether the select is disabled
setDisabled
(disabled?: boolean) => void
Sets the disabled value of the select. If the `disabled` value is not provided, the select will be disabled
errors
string[]
A list of validation errors
setErrors
(errors: string[]) => void
Sets the validation errors