FormsInteractive playground

Select

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

Preparing the playground…

Text and Markdown example

Select · Example

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

Read documentation in Markdown

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

React / Next.js

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

Interactive examples run inside a component with "use client". The playground's Copy button includes the imports needed for the current example.

API reference 0.2.0

Types from the installed published version, including component properties and common HTML attributes. “Optional” does not imply a default value; omitting a property lets the component decide.

Property	Type	Description
`allowCreateWhileLoading`	`boolean`	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`	HTML ID of an element containing an error message related to the input*
`aria-invalid`	`boolean \| "true" \| "false" \| "grammar" \| "spelling"`	Indicate if the value entered in the field is invalid *
`aria-label`	`string`	Accessible name of the control.
`aria-labelledby`	`string`	HTML ID of an element that should be used as the label (for assistive tech)
`aria-live`	`"off" \| "assertive" \| "polite"`	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>`	Customise the messages used by the aria-live component
`autoFocus`	`boolean`	Focus the control when it is mounted
`backspaceRemovesValue`	`boolean`	Remove the currently focused option when the user presses backspace when Select isClearable or isMulti
`blurInputOnSelect`	`boolean`	Remove focus from the input when the user selects an option (handy for dismissing the keyboard on touch devices)
`cacheOptions`	`any`	Keep loaded options for reuse.
`captureMenuScroll`	`boolean`	When the user reaches the top/bottom of the menu, prevent scroll on the scroll-parent
`className`	`string`	Additional CSS classes to customize the element.
`classNamePrefix`	`string \| null`	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>`	Provide classNames based on state for each inner component
`closeMenuOnScroll`	`boolean \| ((event: Event) => boolean)`	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`	Close the select menu when the user selects an option
`components`	`Partial<SelectComponents<Option, IsMulti, Group>>`	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`	Whether the value of the select, e.g. SingleValue, should be displayed in the control.
`createOptionPosition`	`"first" \| "last"`	Sets the position of the createOption element in your options list. Defaults to 'last'
`defaultInputValue`	`string`	Configures defaultInputValue. The type describes the supported values and structure.
`defaultMenuIsOpen`	`boolean`	Configures defaultMenuIsOpen. The type describes the supported values and structure.
`defaultOptions`	`boolean \| OptionsOrGroups<Option, Group>`	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>`	Initial value when the component manages its own state.
`delimiter`	`string`	Delimiter used to join multiple values into a single HTML Input value
`escapeClearsValue`	`boolean`	Clear all values when the user presses escape AND the menu is closed
`filterOption`	`((option: FilterOptionOption<Option>, inputValue: string) => boolean) \| null`	Custom method to filter whether an option should be displayed in the menu
`form`	`string`	Sets the form attribute on the input
`formatCreateLabel`	`((inputValue: string) => ReactNode)`	Gets the label for the "create new ..." option in the menu. Is given the current input value.
`formatGroupLabel`	`((group: Group) => ReactNode)`	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)`	Formats option labels in the menu and control as React components
`getNewOptionData`	`((inputValue: string, optionLabel: ReactNode) => Option)`	Returns the data for the new option when it is created. Used to display the value, and is passed to `onChange`.
`getOptionLabel`	`GetOptionLabel<Option>`	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>`	Resolves option data to a string to compare options and specify value attributes
`hideSelectedOptions`	`boolean`	Hide the selected option from the menu
`id`	`string`	Element identifier; associates labels and descriptions.
`inputId`	`string`	The id of the search input
`inputValue`	`string`	The value of the search input
`instanceId`	`string \| number`	Define an id prefix for the select components e.g. {your-id}-value
`isClearable`	`boolean`	Is the select value clearable
`isCreatable`	`boolean`	Allow creating options. Can be combined with loadOptions.
`isDisabled`	`boolean`	Is the select disabled
`isLoading`	`boolean`	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`	Allow multiple option selection.
`isOptionDisabled`	`((option: Option, selectValue: Options<Option>) => boolean)`	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)`	Override the built-in logic to detect whether an option is selected
`isRtl`	`boolean`	Is the select direction right-to-left
`isSearchable`	`boolean`	Whether to enable search functionality
`isValidNewOption`	`((inputValue: string, value: Options<Option>, options: OptionsOrGroups<Option, Group>, accessors: Accessors<Option>) => boolean)`	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)`	Async: Text to display when loading options
`loadOptions`	`((inputValue: string, callback: (options: OptionsOrGroups<Option, Group>) => void) => void \| Promise<OptionsOrGroups<Option, Group>>)`	Load or filter options and return a promise or use the supported callback.
`maxMenuHeight`	`number`	Maximum height of the menu before scrolling
`menuClassName`	`string`	CSS classes for the specified element.
`menuIsOpen`	`boolean`	Whether the menu is open
`menuPlacement`	`"auto" \| "top" \| "bottom"`	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`	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"`	The CSS position value of the menu, when "fixed" extra layout management is required
`menuShouldBlockScroll`	`boolean`	Whether to block scroll events when the menu is open
`menuShouldScrollIntoView`	`boolean`	Whether the menu should be scrolled into view when it opens
`minMenuHeight`	`number`	Minimum height of the menu before flipping
`mobileSheetOptions`	`OptionsOrGroups<Option, Group>`	Configures mobileSheetOptions. The type describes the supported values and structure.
`mobileSheetTitle`	`string`	Configures mobileSheetTitle. The type describes the supported values and structure.
`name`	`string`	Name used to identify the control in forms.
`noOptionsMessage`	`((obj: { inputValue: string; }) => ReactNode)`	Text to display when there are no options
`onBlur`	`FocusEventHandler<HTMLInputElement>`	Handle blur events on the control
`onChange`	`((newValue: OnChangeValue<Option, IsMulti>, actionMeta: ActionMeta<Option>) => void)`	Change event. Check the type: some controls return an object, others a DOM event.
`onCreateOption`	`((inputValue: string) => void)`	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>`	Handle focus events on the control
`onInputChange`	`((newValue: string, actionMeta: InputActionMeta) => void)`	Handle change events on the input
`onKeyDown`	`KeyboardEventHandler<HTMLDivElement>`	Handle key down events on the select
`onMenuClose`	`(() => void)`	Handle the menu closing
`onMenuOpen`	`(() => void)`	Handle the menu opening
`onMenuScrollToBottom`	`((event: WheelEvent \| TouchEvent) => void)`	Fired when the user scrolls to the bottom of the menu
`onMenuScrollToTop`	`((event: WheelEvent \| TouchEvent) => void)`	Fired when the user scrolls to the top of the menu
`openMenuOnClick`	`boolean`	Allows control of whether the menu is opened when the Select is clicked
`openMenuOnFocus`	`boolean`	Allows control of whether the menu is opened when the Select is focused
`optionClassName`	`string`	CSS classes for the specified element.
`options`	`OptionsOrGroups<Option, Group>`	Component options or configuration. See the type structure.
`pageSize`	`number`	Number of rows per page.
`placeholder`	`ReactNode`	Short hint displayed when there is no value.
`required`	`boolean`	Indicates that a value is required.
`screenReaderStatus`	`((obj: { count: number; }) => string)`	Status to relay to screen readers
`styles`	`StylesConfig<Option, IsMulti, Group>`	Style modifier methods A basic example can be found at the bottom of the [Replacing builtins](/advanced#replacing-builtins) documentation.
`tabIndex`	`number`	Keyboard focus order and availability.
`tabSelectsValue`	`boolean`	Select the currently focused option when the user presses tab
`theme`	`ThemeConfig`	Component theme or theme identifier, depending on the API.
`triggerClassName`	`string`	CSS classes for the specified element.
`value`	`PropsValue<Option>`	Controlled value. Update it from the change callback.

Subcomponents and composition

Review each component's properties and published declaration. Native and accessibility attributes are inherited from the element specified by its type.

Select88 properties

Select · TypeScript

1Select: SelectCallable

SelectTrigger0 properties