Select

A select displays a collapsible list of options and allows a user to select one or more of them.

Installation

npx nextui-cli@latest add select

The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.

Import

NextUI exports 3 select-related components:

• Select: The main component, which is a wrapper for the other components.
• SelectSection: The component that contains a group of select items.
• SelectItem: The component that represents a select item.

Usage

Dynamic items

Select follows the Collection Components API, accepting both static and dynamic collections.

• Static: The usage example above shows the static implementation, which can be used when the full list of options is known ahead of time.
• Dynamic: The example below can be used when the options come from an external data source such as an API call, or update over time.

Multiple Selection

You can use the selectionMode="multiple" property to allow multiple selection.

Disabled

Disabled Items

You can disable specific items by using the disabledKeys property.

Required

If you pass the isRequired property to the select, it will have a danger asterisk at the end of the label and the select will be required.

Sizes

Colors

Variants

Radius

Label Placements

You can change the position of the label by setting the labelPlacement property to inside, outside or outside-left.

Note: If the label is not passed, the labelPlacement property will be outside by default.

Start Content

You can use the startContent and endContent properties to add content to the start and end of the select.

Item Start & End Content

Since the Select component uses the Listbox component under the hood, you can use the startContent and endContent properties of the SelectItem component to add content to the start and end of the select item.

Custom Selector Icon

By default the select uses a chevron-down icon as the selector icon which rotates when the select is open. You can customize this icon by passing a custom one to the selectorIcon property.

Note: Use the disableSelectorIconRotation property to disable the rotation of the icon.

Without Scroll Shadow

Select component uses the ScrollShadow under the hood to show a shadow when the select content is scrollable. You can disable this shadow by passing using the scrollShadowProps property.

Note: You can also use the showScrollIndicators property to disable the scroll indicators.

With Description

You can add a description to the select by passing the description property.

With Error Message

You can combine the isInvalid and errorMessage properties to show an invalid select.

Clear Button

If you pass the isClearable property to the select, it will have a clear button which will be visible only when some value is selected.

Controlled

You can use the selectedKeys and onSelectionChange / onChange properties to control the select value.

Using onSelectionChange:

Using onChange:

Controlling the open state

You can control the open state of the select by using the isOpen and onOpenChange / onClose properties.

Custom Items

You can customize the select items by modifying the SelectItem children.

Custom Render Value

By default the select will render the selected item's text value, but you can customize this by passing a renderValue function.

The renderValue function receives the selected items as a parameter and must return a ReactNode. Check the Render Value Function section for more details.

Asynchronous Loading

Select supports asynchronous loading, in the example below we are using a custom hook to fetch the Pokemon API data in combination with the useInfiniteScroll hook to load more data when the user reaches the end of the list.

The isLoading prop is used to show a loading indicator instead of the selector icon when the data is being fetched.

npm install @nextui-org/use-infinite-scroll

import {useInfiniteScroll} from "@nextui-org/use-infinite-scroll";

With Sections

You can use the SelectSection component to group select items.

Custom Sections Style

You can customize the sections style by using the classNames property of the SelectSection component.

Multiple Select Controlled

You can use the same properties as the single select to control the multiple select, selectedKeys and onSelectionChange / onChange.

Using onSelectionChange:

Using onChange:

Multiple With Chips

You can render any component as the select value by using the renderValue property. In this example we are using the Chip component to render the selected items.

Note: Make sure to pass the isMultiline property to the Select component to allow the chips to wrap.

The renderValue function receives the selected items as a parameter and must return a ReactNode. Check the Render Value Function section for more details.

Customizing the select

You can customize any slot of the select by using the classNames property. Select component also provides the popoverProps and listboxProps properties to customize the popover and listbox components.

Slots

• base: The main wrapper of the select. This wraps the rest of the slots.
• label: The label of the select.
• mainWrapper: Wraps the helperWrapper and the trigger slots.
• trigger: The trigger of the select. This wraps the label the inner wrapper and the selector icon.
• innerWrapper: The wrapper of the select content. This wraps the start/end content and the select value.
• selectorIcon: The selector icon of the select. This is the icon that rotates when the select is open (data-open).
• value: The select value. This is also the slot that wraps the renderValue function result.
• listboxWrapper: The wrapper of the listbox. This wraps the listbox component, this slot is used on top of the scroll shadow component.
• listbox: The listbox component. This is the component that wraps the select items.
• popoverContent: The popover content slot. Use this to modify the popover content styles.
• helperWrapper: The wrapper of the helper text. This wraps the helper text and the error message.
• description: The description of the select.
• errorMessage: The error message of the select.

Data Attributes

Select has the following attributes on the base element:

• data-filled: Indicates if the select has a value, is focused, has start/end content or is open.
• data-has-value: Indicates if the select has selected item(s).
• data-has-label: Indicates if the select has a label. Based on label prop.
• data-has-helper: Indicates if the select has helper text. Based on errorMessage or description prop.
• data-invalid: Indicates if the select is invalid. Based on isInvalid prop.

Select has the following attributes on the trigger element:

• data-open: Indicates if the select is open.
• data-disabled: When the select trigger is disabled. Based on select isDisabled prop.
• data-focus: When the select trigger is being focused. Based on useFocusRing.
• data-focus-visible: When the select trigger is being focused with the keyboard. Based on useFocusRing.
• data-pressed: When the select trigger is pressed. Based on usePress
• data-hover: When the select trigger is being hovered. Based on useHover

Select has the following attributes on the selectorIcon element:

• data-open: Indicates if the select is open.

SelectItem has the following attributes on the base element:

• data-disabled: When the select item is disabled. Based on select disabledKeys prop.
• data-selected: When the select item is selected. Based on select selectedKeys prop.
• data-hover: When the select item is being hovered. Based on useHover
• data-pressed: When the select item is pressed. Based on usePress
• data-focus: When the select item is being focused. Based on useFocusRing.
• data-focus-visible: When the select item is being focused with the keyboard. Based on useFocusRing.

Accessibility

• Exposed to assistive technology as a button with a listbox popup using ARIA (combined with Listbox).
• Support for selecting a single option.
• Support for selecting multiple options.
• Support for disabled options.
• Support for sections.
• Labeling support for accessibility.
• Support for description and error message help text linked to the input via ARIA.
• Support for mouse, touch, and keyboard interactions.
• Tab stop focus management.
• Keyboard support for opening the listbox using the arrow keys, including automatically focusing the first or last item accordingly.
• Typeahead to allow selecting options by typing text, even without opening the listbox.
• Browser autofill integration via a hidden native <select> element.
• Support for mobile form navigation via software keyboard.
• Mobile screen reader listbox dismissal support.

API

Select Props

Select Events

SelectItem Props

Check the ListboxItem props.

SelectItem Events

Check the ListboxItem events.

SelectSection Props

Check the ListboxSection props.

Types

Render Value Function

The T type is the type of the data passed to the select items.

export type SelectedItemProps<T> = {
  /** A unique key for the item. */
  key?: Key;
  /** The props passed to the item. */
  props?: Record<string, any>;
  /** The item data. */
  data?: T | null;
  /** An accessibility label for this item. */
  "aria-label"?: string;
  /** The rendered contents of this item (e.g. JSX). */
  rendered?: ReactNode;
  /** A string value for this item, used for features like typeahead. */
  textValue?: string;
  /** The type of item this item represents. */
  type?: string;
};

type SelectedItems<T> = Array<SelectedItemProps<T>>;

renderValue: (items: SelectedItems<T>) => ReactNode;