TagPicker #

Multi-select by tag and support new options

Import #

Examples #

Basic #

Size #

Block #

Group #

Creatable #

Custom #

Disabled and read only #

Async #

Accessibility #

ARIA properties #

• TagPicker 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.
• listbox has the aria-multiselectable=true attribute to indicate that the listbox is multi-selectable.

Keyboard interactions #

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

Props #

<TagPicker> #

Property	Type(Default)	Description
cacheData	ItemDataType[]	Option to cache value when searching asynchronously
classPrefix	string ('picker')	The prefix of the component CSS class
cleanable	boolean (true)	Whether the selected value can be cleared
container	HTMLElement | (() => HTMLElement)	Sets the rendering container
creatable	boolean	Settings can create new options
data *	ItemDataType[]	The data of component
defaultValue	string[]	Default values of the selected items
disabled	boolean	Whether disabled component
disabledItemValues	string[]	Disable item by value
groupBy	string	Set group condition key in data
labelKey	string ('label')	Set label key in data
listProps	ListProps	Properties of virtualized lists.
loading	boolean (false)	Whether to display a loading state indicator
locale	PickerLocaleType	Define localization settings to show component text in the user's regional language
menuClassName	string	A css class to apply to the Menu DOM node.
menuMaxHeight	number (320)	The max height of Dropdown
menuStyle	CSSProperties	A style to apply to the Menu DOM node.
onChange	(value:string[], event) => void	Callback fired when value change
onClean	(event) => void	Callback fired when value clean
onClose	() => void	Callback fired when close component
onCreate	(value: string[], item: ItemDataType, event) => void	Callback fired when a new option is created
onEnter	() => void	Callback fired before the overlay transitions in
onEntered	() => void	Callback fired after the overlay finishes transitioning in
onEntering	() => void	Callback fired as the overlay begins to transition in
onExit	() => void	Callback fired right before the overlay transitions out
onExited	() => void	Callback fired after the overlay finishes transitioning out
onExiting	() => void	Callback fired as the overlay begins to transition out
onGroupTitleClick	(event) => void	Callback fired when click the group title
onOpen	() => void	Callback fired when open component
onSearch	(searchKeyword:string, event) => void	Callback fired when search
onSelect	(value:string[], item: ItemDataType , event) => void	Callback fired when item is selected
onTagRemove	(value: string, event: MouseEvent) => void	Callback fired when tag remove
open	boolean	Whether open the component
placeholder	ReactNode ('Select')	Setting placeholders
placement	Placement('bottomStart')	The placement of component
preventOverflow	boolean	Prevent floating element overflow
renderExtraFooter	() => ReactNode	Custom render extra footer
renderMenu	(menu: ReactNode) => ReactNode	Custom render menu
renderMenuGroup	(groupTitle: ReactNode, item: ItemDataType) => ReactNode	Custom render menu group
renderMenuItem	(label:ReactNode, item: ItemDataType) => ReactNode	Custom render menu items
renderMenuItemCheckbox	(checkboxProps: CheckboxProps) => ReactNode	Custom render menu items checkbox
renderValue	(value: string[], items:ItemDataType[], tags:ReactNode[]) => ReactNode	Custom render selected items
searchable	boolean (true)	Whether dispaly search input box
searchBy	(keyword: string, label: ReactNode, item: ItemDataType) => boolean	Custom search rules
size	'lg' | 'md' | 'sm' | 'xs' ('md')	A picker can have different sizes
sort	(isGroup: boolean) => (a: any, b: any) => number	Sort options
tagProps	TagProps	Set the props of the Tag
toggleAs	ElementType ('a')	You can use a custom element for this component
trigger	'Enter' | 'Space' | 'Comma' ('Enter')	Set the trigger for creating tags
value	string[]	Specifies the values of the selected items (Controlled)
valueKey	string ('value')	Set value key in data
virtualized	boolean	Whether using Virtualized List

ItemDataType #

interface ItemDataType<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?: ItemDataType<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;
}