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.
tsx
Copied
1
<Select id="selectCat" data={["Cat1", "Cat2", "Cat3"]} placeholder="Select a cat" />
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. As long as the task output matches the type of data, the data options are automatically inferred from the output.
tsx
Copied
1
<Select id="selectCat" task="list_cat_breeds" placeholder="Select a cat" />

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.
tsx
Copied
1
<Select
2
  id="selectCat"
3
  task="list_cats_sql"
4
  outputTransform={(cats) => cats.Q1.map((cat) => cat.name)}
5
  placeholder="Select a cat"
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
<Select
2
  id="selectCat"
3
  task="list_cat_breeds"
4
  outputTransform={(catBreeds) =>
5
    catBreeds.map((breed) => ({ label: breed.toUpperCase(), value: breed }))
6
  }
7
  placeholder="Select a cat breed"
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
<Select
2
  id="selectCat"
3
  data={[
4
    { label: "Bootz", value: "Cat1" },
5
    { label: "Hazel", value: "Cat2" },
6
    { label: "Baosky", value: "Cat3" },
7
  ]}
8
  placeholder="Select a cat"
9
/>

Disabling
The entire Select can be disabled using defaultDisabled.
tsx
Copied
1
<Select
2
  id="selectCat"
3
  data={["Cat1", "Cat2", "Cat3"]}
4
  placeholder="Select a cat"
5
  defaultDisabled
6
/>
Individual options can be disabled by setting disabled: true on the option.
tsx
Copied
1
<Select
2
  id="selectCat"
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 a cat"
9
/>

Grouping
Options can be grouped together by specifying the group prop on each option.
tsx
Copied
1
<Select
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 a pet"
8
/>

Component API
ItemComponent
optional
ItemComponent

The component with which the item is rendered.

allowDeselect
optional
Default
false
boolean

Allow deselecting items on click.

autoFocus
optional
boolean

Whether to automatically focus on the select input.

clearable
optional
Default
false
boolean

Allows clearing the selected item when true.

data
optional
(string | number | SelectItem)[]

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

defaultDisabled
optional
boolean

Initial disabled state of the select.

defaultValue
optional
string | number

Initial value of the select.

description
optional
Component

Select description, displayed below the select 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 select.

error
optional
Component

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

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

Custom function that filters the select 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.

label
optional
Component

Select label, displayed before the select input. Can be a string or a React component.

loading
optional
boolean

Renders a loading indicator when true.

nothingFound
optional
Component

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

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

Callback on select value change.

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

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 select element.

readOnly
optional
boolean

If true, the select component is read only.

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

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 (true by default), executeOnReconnect (true by default), and executeOnWindowFocus (false by default) params control when the task is (re)run - on component mount, when the window is (re)focused, and if the network reconnects.

unstyled
optional
boolean

If true, the select component is rendered without any styling applied. The select dropdown is transparant and no padding is applied.

validate
optional
((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.

value
optional
string | number

Controlled value of the select. 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 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.

State API
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

setValue
(value: TValue | undefined) => void

Sets the value of the select. Set the value as undefined to clear the selection

value
TValue | undefined

The selected value

PrivacyTermsSupport