# Select

Selection with search, groups, asynchronous loading and option creation.

## How to use it

The API uses options with label/value objects; onChange receives the selected object. loadOptions enables asynchronous loading; isCreatable allows new options and can be combined with loadOptions. Use defaultOptions for initial loading and cacheOptions to reuse searches. Do not compose SelectItem as a Radix Select: compatibility exports are HTML elements.



## Import


```tsx
import { Select, SelectTrigger, SelectValue, SelectContent, SelectGroup, SelectLabel, SelectItem, SelectSeparator, SelectScrollDownButton, SelectScrollUpButton } from "@kivora/nextjs";
```


Examples run in a Client Component. Also import the hooks, icons and dependencies used. This is the web API; consult the native guide for React Native.

## Example


```tsx
<Select aria-label="Framework" placeholder="Choose your framework" options={[{value:"next",label:"Next.js"},{value:"react",label:"React"},{value:"native",label:"React Native"}]} />
```


## Asynchronous loading

```tsx
<Select aria-label="Search frameworks" defaultOptions cacheOptions loadOptions={async (query) => [{value:"next",label:"Next.js"},{value:"react",label:"React"}].filter(option => option.label.toLowerCase().includes(query.toLowerCase()))} />
```


## Create options

```tsx
<Select isCreatable aria-label="Tags" isMulti placeholder="Select or create…" options={[{value:"design",label:"Design"},{value:"dev",label:"Development"}]} />
```


## Load and create

```tsx
<Select isCreatable isMulti aria-label="Search or create" defaultOptions loadOptions={async (query) => [{value:"react",label:"React"}].filter(option => option.label.toLowerCase().includes(query.toLowerCase()))} />
```


## Multiple selection

```tsx
<Select aria-label="Technologies" isMulti options={[{value:"ts",label:"TypeScript"},{value:"react",label:"React"},{value:"css",label:"CSS"}]} />
```


## API: Select


```typescript
Select: SelectCallable
```


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| allowCreateWhileLoading | boolean | No | Allow options to be created while the `isLoading` prop is true. Useful to prevent the "create new ..." option being displayed while async results are still being loaded. |
| aria-errormessage | string | No | HTML ID of an element containing an error message related to the input* |
| aria-invalid | boolean \| "true" \| "false" \| "grammar" \| "spelling" | No | Indicate if the value entered in the field is invalid * |
| aria-label | string | No | Accessible name of the control. |
| aria-labelledby | string | No | HTML ID of an element that should be used as the label (for assistive tech) |
| aria-live | "off" \| "assertive" \| "polite" | No | Used to set the priority with which screen reader should treat updates to live regions. The possible settings are: off, polite (default) or assertive |
| ariaLiveMessages | AriaLiveMessages<Option, IsMulti, Group> | No | Customise the messages used by the aria-live component |
| autoFocus | boolean | No | Focus the control when it is mounted |
| backspaceRemovesValue | boolean | No | Remove the currently focused option when the user presses backspace when Select isClearable or isMulti |
| blurInputOnSelect | boolean | No | Remove focus from the input when the user selects an option (handy for dismissing the keyboard on touch devices) |
| cacheOptions | any | No | Keep loaded options for reuse. |
| captureMenuScroll | boolean | No | When the user reaches the top/bottom of the menu, prevent scroll on the scroll-parent |
| className | string | No | Additional CSS classes to customize the element. |
| classNamePrefix | string \| null | No | If provided, all inner components will be given a prefixed className attribute.  This is useful when styling via CSS classes instead of the Styles API approach. |
| classNames | ClassNamesConfig<Option, IsMulti, Group> | No | Provide classNames based on state for each inner component |
| closeMenuOnScroll | boolean \| ((event: Event) => boolean) | No | If `true`, close the select menu when the user scrolls the document/body.  If a function, takes a standard javascript `ScrollEvent` you return a boolean:  `true` => The menu closes  `false` => The menu stays open  This is useful when you have a scrollable modal and want to portal the menu out, but want to avoid graphical issues. |
| closeMenuOnSelect | boolean | No | Close the select menu when the user selects an option |
| components | Partial<SelectComponents<Option, IsMulti, Group>> | No | This complex object includes all the compositional components that are used in `react-select`. If you wish to overwrite a component, pass in an object with the appropriate namespace.  If you only wish to restyle a component, we recommend using the `styles` prop instead. For a list of the components that can be passed in, and the shape that will be passed to them, see [the components docs](/components) |
| controlShouldRenderValue | boolean | No | Whether the value of the select, e.g. SingleValue, should be displayed in the control. |
| createOptionPosition | "first" \| "last" | No | Sets the position of the createOption element in your options list. Defaults to 'last' |
| defaultInputValue | string | No | See the published type. |
| defaultMenuIsOpen | boolean | No | See the published type. |
| defaultOptions | boolean \| OptionsOrGroups<Option, Group> | No | The default set of options to show before the user starts searching. When set to `true`, the results for loadOptions('') will be autoloaded. |
| defaultValue | PropsValue<Option> | No | Initial value when the component manages its own state. |
| delimiter | string | No | Delimiter used to join multiple values into a single HTML Input value |
| escapeClearsValue | boolean | No | Clear all values when the user presses escape AND the menu is closed |
| filterOption | ((option: FilterOptionOption<Option>, inputValue: string) => boolean) \| null | No | Custom method to filter whether an option should be displayed in the menu |
| form | string | No | Sets the form attribute on the input |
| formatCreateLabel | ((inputValue: string) => ReactNode) | No | Gets the label for the "create new ..." option in the menu. Is given the current input value. |
| formatGroupLabel | ((group: Group) => ReactNode) | No | Formats group labels in the menu as React components  An example can be found in the [Replacing builtins](/advanced#replacing-builtins) documentation. |
| formatOptionLabel | ((data: Option, formatOptionLabelMeta: FormatOptionLabelMeta<Option>) => ReactNode) | No | Formats option labels in the menu and control as React components |
| getNewOptionData | ((inputValue: string, optionLabel: ReactNode) => Option) | No | Returns the data for the new option when it is created. Used to display the value, and is passed to `onChange`. |
| getOptionLabel | GetOptionLabel<Option> | No | Resolves option data to a string to be displayed as the label by components  Note: Failure to resolve to a string type can interfere with filtering and screen reader support. |
| getOptionValue | GetOptionValue<Option> | No | Resolves option data to a string to compare options and specify value attributes |
| hideSelectedOptions | boolean | No | Hide the selected option from the menu |
| id | string | No | Element identifier; associates labels and descriptions. |
| inputId | string | No | The id of the search input |
| inputValue | string | No | The value of the search input |
| instanceId | string \| number | No | Define an id prefix for the select components e.g. {your-id}-value |
| isClearable | boolean | No | Is the select value clearable |
| isCreatable | boolean | No | Allow creating options. Can be combined with loadOptions. |
| isDisabled | boolean | No | Is the select disabled |
| isLoading | boolean | No | Is the select in a state of loading (async) Will cause the select to be displayed in the loading state, even if the Async select is not currently waiting for loadOptions to resolve |
| isMulti | IsMulti | No | Allow multiple option selection. |
| isOptionDisabled | ((option: Option, selectValue: Options<Option>) => boolean) | No | Override the built-in logic to detect whether an option is disabled  An example can be found in the [Replacing builtins](/advanced#replacing-builtins) documentation. |
| isOptionSelected | ((option: Option, selectValue: Options<Option>) => boolean) | No | Override the built-in logic to detect whether an option is selected |
| isRtl | boolean | No | Is the select direction right-to-left |
| isSearchable | boolean | No | Whether to enable search functionality |
| isValidNewOption | ((inputValue: string, value: Options<Option>, options: OptionsOrGroups<Option, Group>, accessors: Accessors<Option>) => boolean) | No | Determines whether the "create new ..." option should be displayed based on the current input value, select value and options array. |
| loadingMessage | ((obj: { inputValue: string; }) => ReactNode) | No | Async: Text to display when loading options |
| loadOptions | ((inputValue: string, callback: (options: OptionsOrGroups<Option, Group>) => void) => void \| Promise<OptionsOrGroups<Option, Group>>) | No | Load or filter options and return a promise or use the supported callback. |
| maxMenuHeight | number | No | Maximum height of the menu before scrolling |
| menuClassName | string | No | See the published type. |
| menuIsOpen | boolean | No | Whether the menu is open |
| menuPlacement | "auto" \| "top" \| "bottom" | No | Default placement of the menu in relation to the control. 'auto' will flip when there isn't enough space below the control. |
| menuPortalTarget | HTMLElement \| null | No | Whether the menu should use a portal, and where it should attach  An example can be found in the [Portaling](/advanced#portaling) documentation |
| menuPosition | "absolute" \| "fixed" | No | The CSS position value of the menu, when "fixed" extra layout management is required |
| menuShouldBlockScroll | boolean | No | Whether to block scroll events when the menu is open |
| menuShouldScrollIntoView | boolean | No | Whether the menu should be scrolled into view when it opens |
| minMenuHeight | number | No | Minimum height of the menu before flipping |
| mobileSheetOptions | OptionsOrGroups<Option, Group> | No | See the published type. |
| mobileSheetTitle | string | No | See the published type. |
| name | string | No | Name used to identify the control in forms. |
| noOptionsMessage | ((obj: { inputValue: string; }) => ReactNode) | No | Text to display when there are no options |
| onBlur | FocusEventHandler<HTMLInputElement> | No | Handle blur events on the control |
| onChange | ((newValue: OnChangeValue<Option, IsMulti>, actionMeta: ActionMeta<Option>) => void) | No | Change event. Check the type: some controls return an object, others a DOM event. |
| onCreateOption | ((inputValue: string) => void) | No | If provided, this will be called with the input value when a new option is created, and `onChange` will **not** be called. Use this when you need more control over what happens when new options are created. |
| onFocus | FocusEventHandler<HTMLInputElement> | No | Handle focus events on the control |
| onInputChange | ((newValue: string, actionMeta: InputActionMeta) => void) | No | Handle change events on the input |
| onKeyDown | KeyboardEventHandler<HTMLDivElement> | No | Handle key down events on the select |
| onMenuClose | (() => void) | No | Handle the menu closing |
| onMenuOpen | (() => void) | No | Handle the menu opening |
| onMenuScrollToBottom | ((event: WheelEvent \| TouchEvent) => void) | No | Fired when the user scrolls to the bottom of the menu |
| onMenuScrollToTop | ((event: WheelEvent \| TouchEvent) => void) | No | Fired when the user scrolls to the top of the menu |
| openMenuOnClick | boolean | No | Allows control of whether the menu is opened when the Select is clicked |
| openMenuOnFocus | boolean | No | Allows control of whether the menu is opened when the Select is focused |
| optionClassName | string | No | See the published type. |
| options | OptionsOrGroups<Option, Group> | No | Component options or configuration. See the type structure. |
| pageSize | number | No | Number of rows per page. |
| placeholder | ReactNode | No | Short hint displayed when there is no value. |
| required | boolean | No | Indicates that a value is required. |
| screenReaderStatus | ((obj: { count: number; }) => string) | No | Status to relay to screen readers |
| styles | StylesConfig<Option, IsMulti, Group> | No | Style modifier methods  A basic example can be found at the bottom of the [Replacing builtins](/advanced#replacing-builtins) documentation. |
| tabIndex | number | No | Keyboard focus order and availability. |
| tabSelectsValue | boolean | No | Select the currently focused option when the user presses tab |
| theme | ThemeConfig | No | Component theme or theme identifier, depending on the API. |
| triggerClassName | string | No | See the published type. |
| value | PropsValue<Option> | No | Controlled value. Update it from the change callback. |

## API: SelectScrollDownButton


```typescript
SelectScrollDownButton: React.ExoticComponent<React.FragmentProps>
```


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| children | ReactNode | No | Content or child elements of the component. |

## API: SelectScrollUpButton


```typescript
SelectScrollUpButton: React.ExoticComponent<React.FragmentProps>
```


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| children | ReactNode | No | Content or child elements of the component. |

Source: https://kivora.pro/docs/componentes/select