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