Select

The Select component allows user to search for and pick an option from the given data.

Basic usage

The Select component must have a set of data options that the user can choose from.
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.

Customizing data

To use a task that outputs a format that isn't expected by Select, use outputTransform to convert the output. This prop is a function that receives the Select data and returns new data. For example, a SQL task may return two columns, name and breed. If we want to build a 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 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 | 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
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 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.
false
allowDeselect
boolean
Allow deselecting items on click.
false
initiallyOpened
boolean
Initial dropdown opened state.
false
itemComponent
ItemComponent
The component with which the item is rendered.
withinPortal
boolean
If true, the select dropdown is rendered in a React portal. Use this if the select is in a table or dialog and is cut off by its parent container.
unstyled
boolean
If true, the select component is rendered without any styling applied. The select dropdown is transparant and no padding is applied.
readOnly
boolean
If true, the select component is read only.
task
string | { slug: string; params?: Record<string, any>; refetchInterval?: number; onSuccess?: (output?: TOutput) => void; onFailure?: (output?: TOutput, error?: TError) => void; executeOnMount?: boolean; executeOnWindowFocus?: boolean; executeOnReconnect?: boolean; } | AirplaneFunc | { fn: AirplaneFunc; params?: Record<string, any>; refetchInterval?: number; onSuccess?: (output?: TOutput) => void; onFailure?: (output?: TOutput, error?: TError) => void; executeOnMount?: boolean; executeOnWindowFocus?: {boolean; executeOnReconnect?: boolean; }

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 requires parameters, these can be passed in via params.

The refetchInterval param represents how often (in milliseconds) the task query should be rerun to refetch data automatically.

The onSuccess and onFailure 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.

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