SelectPicker

For a single data selection, support grouping.

Import

MainIndividual
import { SelectPicker } from 'rsuite';

Examples

Basic

With a label

Appearance

Size

Block

Loading state

When the picker is loading, a spinner is displayed to indicate the loading state. Clicking a loading picker won't open its options menu.

Group

Placement and Prevent overflow

Custom options

Country select

Disabled and read only

Disable Search

Async

Controlled

Virtualize Long Lists

Infinite loader

Responsive

Accessibility

ARIA properties

  • SelectPicker has role combobox.
  • Has the aria-haspopup="listbox" attribute to indicate that the combobox has a popup listbox.
  • Has the aria-expanded attribute to indicate whether the listbox is open or not.
  • Has the aria-controls attribute to indicate the ID of the listbox element.
  • Has the aria-activedescendant attribute to indicate the ID of the focused option.
  • When label is set, the aria-labelledby attribute is added to the combobox element and the listbox element and is set to the value of the id attribute of label.

Keyboard interactions

  • ↓ - Move focus to the next option.
  • ↑ - Move focus to the previous option.
  • Enter - Select the focused option.
  • Esc - Close the listbox.

Props

<SelectPicker>

Property Type (Default) Description
appearance 'default' | 'subtle' ('default') Set picker appearance
block boolean Render the component as a block element
caretAs ElementType Custom component for the caret icon
classPrefix string ('picker') The prefix for the component CSS class
cleanable boolean (true) Whether the value can be cleared
container HTMLElement | (() => HTMLElement) Sets the rendering container
data * Option[] The data for the component
defaultValue Value Default value (uncontrolled)
disabled boolean Whether the component is disabled
disabledItemValues Value[] Values of disabled items
groupBy string Key for grouping data items
label ReactNode Label displayed at the beginning of the toggle button
labelKey string ('label') Key for the label in data items
listboxMaxHeight number (320) Maximum height of the listbox
listProps ListProps Properties for virtualized lists
loading boolean (false) Whether to show a loading state
locale PickerLocaleType Locale settings for component text
onChange (value: Value, event) => void Callback fired when value changes
onClean (event) => void Callback fired when value is cleared
onClose () => void Callback fired when component closes
onEnter () => void Callback fired before overlay transitions in
onEntered () => void Callback fired after overlay finishes transitioning in
onEntering () => void Callback fired as overlay begins to transition in
onExit () => void Callback fired before overlay transitions out
onExited () => void Callback fired after overlay finishes transitioning out
onExiting () => void Callback fired as overlay begins to transition out
onGroupTitleClick (event) => void Callback fired when group header is clicked
onOpen () => void Callback fired when component opens
onSearch (searchKeyword: string, event) => void Callback fired when search is performed
onSelect (value: Value, item: Option, event) => void Callback fired when an item is selected
open boolean Whether the component is open
placeholder ReactNode ('Select') Placeholder text
placement Placement('bottomStart') The placement of the component
popupClassName string Custom class name for the popup
popupStyle CSSProperties Custom style for the popup
preventOverflow boolean Prevent floating element overflow
renderExtraFooter () => ReactNode Custom render function for extra footer
renderListbox (listbox: ReactNode) => ReactNode Custom render function for listbox
renderOption (label: ReactNode, item: Option) => ReactNode Custom render function for options
renderOptionGroup (title: ReactNode, item: Option) => ReactNode Custom render function for option groups
renderValue (value: Value, item: Option, selected:ReactNode) => ReactNode Custom render function for selected value
searchable boolean (true) Whether the component is searchable
searchBy (keyword:string, label:ReactNode, item: Option) => boolean Custom search function
size 'lg' | 'md' | 'sm' | 'xs' ('md') Size of the component
sort (isGroup: boolean) => (a: any, b: any) => number Custom sort function for options
toggleAs ElementType ('a') Custom element for the component
value Value Current value (controlled)
valueKey string ('value') Key for the value in data items
virtualized boolean Whether to use virtualized list

Option 

interface Option<V> {
  /** The value of the option corresponds to the `valueKey` in the data. **/
  value: V;

  /** The content displayed by the option corresponds to the `labelKey` in the data. **/
  label: ReactNode;

  /**
   * The data of the child option corresponds to the `childrenKey` in the data.
   * Properties owned by tree structure components, such as TreePicker, Cascader.
   */
  children?: Option<V>[];

  /**
   * Properties of grouping functional components, such as CheckPicker, InputPicker
   */
  groupBy?: string;

  /**
   * The children under the current node are loading.
   * Used for components that have cascading relationships and lazy loading of children. E.g. Cascader, MultiCascader
   */
  loading?: boolean;
}

Placement 

type Placement =
  | 'bottomStart'
  | 'bottomEnd'
  | 'topStart'
  | 'topEnd'
  | 'leftStart'
  | 'leftEnd'
  | 'rightStart'
  | 'rightEnd'
  | 'auto'
  | 'autoVerticalStart'
  | 'autoVerticalEnd'
  | 'autoHorizontalStart'
  | 'autoHorizontalEnd';

ListProps 

interface ListProps {
  /**
   * Size of a item in the direction being windowed.
   */
  itemSize?: number | ((index: number) => number);

  /**
   * Scroll offset for initial render.
   */
  initialScrollOffset?: number;

  /**
   * Called when the items rendered by the list change.
   */
  onItemsRendered?: (props: ListOnItemsRenderedProps) => void;

  /**
   * Called when the list scroll positions changes, as a result of user scrolling or scroll-to method calls.
   */
  onScroll?: (props: ListOnScrollProps) => void;
}

Value 

type Value = string | number;