TagsInput

Multi-select combobox that renders selected values as removable tags.

Examples

Default

Team

Ada Lovelace

<TagsInput label="Team" onChange={() => {}} placeholder="Search people" />

Empty

Team

<EmptyTagsInputStory {...args} />

Creatable

Team

Ada Lovelace

<TagsInput
  label="Team"
  onChange={() => {}}
  placeholder="Search people"
  hasCreate
/>

With Clear

Team

Ada Lovelace

Clear Team

<TagsInput
  label="Team"
  onChange={() => {}}
  placeholder="Search people"
  hasClear
/>

Async Search

Team

<AsyncSearchStory {...args} />

Max Entries

Team

Ada Lovelace

<TagsInput
  label="Team"
  onChange={() => {}}
  placeholder="Search people"
  maxEntries={2}
/>

Disabled

Team

Ada Lovelace

<TagsInput
  label="Team"
  onChange={() => {}}
  placeholder="Search people"
  isDisabled
/>

Read Only

Team

Ada Lovelace

<TagsInput
  label="Team"
  onChange={() => {}}
  placeholder="Search people"
  hasClear
  isReadOnly
/>

Small

Team

Ada Lovelace

<TagsInput
  label="Team"
  onChange={() => {}}
  placeholder="Search people"
  size="sm"
/>

Large

Team

Ada Lovelace

<TagsInput
  label="Team"
  onChange={() => {}}
  placeholder="Search people"
  size="lg"
/>

Required

Team · Required

Ada Lovelace

<TagsInput
  label="Team"
  onChange={() => {}}
  placeholder="Search people"
  isRequired
/>

Error

Team

Ada Lovelace

At least one team member is required.

<TagsInput
  label="Team"
  onChange={() => {}}
  placeholder="Search people"
  status={{message: 'At least one team member is required.', type: 'error'}}
/>

Warning

Team

Ada Lovelace

This team has limited capacity.

<TagsInput
  label="Team"
  onChange={() => {}}
  placeholder="Search people"
  status={{message: 'This team has limited capacity.', type: 'warning'}}
/>

Overflow Inline

Team

Ada LovelaceGrace HopperKatherine JohnsonMargaret Hamilton

+4 more

Ada LovelaceGrace HopperKatherine JohnsonMargaret Hamilton

<OverflowInlineStory {...args} />

Overflow Behaviors

Inline overflow

Ada LovelaceGrace HopperKatherine JohnsonMargaret HamiltonHedy Lamarr

+5 more

Ada LovelaceGrace HopperKatherine JohnsonMargaret HamiltonHedy Lamarr

Popover overflow

Ada LovelaceGrace HopperKatherine JohnsonMargaret HamiltonHedy Lamarr

+5 more

Ada LovelaceGrace HopperKatherine JohnsonMargaret HamiltonHedy Lamarr

Ada LovelaceGrace HopperKatherine JohnsonMargaret HamiltonHedy Lamarr

+5 more

Ada LovelaceGrace HopperKatherine JohnsonMargaret HamiltonHedy Lamarr

<OverflowBehaviorsStory {...args} />

API

TagsInput

Multi-select combobox that renders selected values as removable tags.

When isOptional: false, isRequired: false

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the input wrapper.
data-testid	string	—	Test ID applied to the input wrapper.
debounceMs	number	150	Debounce delay in milliseconds before search runs.
description	ReactNode	—	Supporting text rendered below the label.
emptySearchResultsText	string	'No results found'	Empty state text.
endContent	ReactNode	—	Content rendered at the end of the input row.
handleRef	Ref<TagsInputHandle>	—	Imperative focus/blur handle.
hasAutoFocus	boolean	false	Whether to focus the input on mount.
hasClear	boolean	false	Whether to show a clear button that removes all tags.
hasEntriesOnFocus	boolean	false	Whether to show bootstrap results on focus before typing.
isDisabled	boolean	false	Whether the input is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label.
isReadOnly	boolean	false	Whether the input is read-only. Prevents typing and hides the clear button without applying disabled opacity.
label*	string	—	Field label.
labelIcon	IconComponent	—	Icon shown before the label.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
maxEntries	number	—	Maximum number of selected tags.
maxMenuItems	number	10	Maximum number of menu items.
onBlur	(event: FocusEvent<HTMLDivElement>) => void	—	Called when focus leaves the tags-input.
onChange*	(items: T[], change: TagsInputChange<T>) => void	—	Called when selected tags change.
onFocus	(event: FocusEvent<HTMLDivElement>) => void	—	Called when focus enters the tags-input.
onQueryChange	(query: string) => void	—	Called when the query changes.
placeholder	string	—	Placeholder text.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the field root.
renderItem	(item: T) => ReactNode	—	Custom result renderer.
renderTag	(item: T, onRemove: () => void) => ReactNode	—	Custom tag renderer.
searchSource*	SearchSource<T>	—	Provides results for the menu. Use createStaticSearchSource for in-memory data, or implement SearchSource for async/remote search.
size	"sm" | "md" | "lg"	'md'	Visual size.
startIcon	IconComponent	—	Icon shown before the input.
status	InputStatus	—	Validation status displayed below the tags-input.
style	CSSProperties	—	Inline styles applied to the input wrapper.
tagOverflowBehavior	"none" | "unfocusedInline" | "unfocusedLayer"	'none'	Controls how tags overflow when the container is too narrow. - 'none': Tags wrap to multiple lines (default). - 'unfocusedInline': Single line with "+ N more" when unfocused; expands inline on focus. - 'unfocusedLayer': Single line with "+ N more" when unfocused; expands as overlay on focus.
value*	T[]	—	Selected items.
isOptional	false	—
isRequired	false	—
hasCreate	boolean	false	Whether users can create a tag from free text.
createItem	(rawValue: string) => T	—	Builds the committed item from the typed text. Optional for this item type because the default builder — rawValue => ({id: rawValue, label: rawValue}) — already produces a valid item. Builds the committed item from the typed text. Required for this item type because it has fields the default {id, label} builder cannot supply.

When isOptional: true, isRequired: false

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the input wrapper.
data-testid	string	—	Test ID applied to the input wrapper.
debounceMs	number	150	Debounce delay in milliseconds before search runs.
description	ReactNode	—	Supporting text rendered below the label.
emptySearchResultsText	string	'No results found'	Empty state text.
endContent	ReactNode	—	Content rendered at the end of the input row.
handleRef	Ref<TagsInputHandle>	—	Imperative focus/blur handle.
hasAutoFocus	boolean	false	Whether to focus the input on mount.
hasClear	boolean	false	Whether to show a clear button that removes all tags.
hasEntriesOnFocus	boolean	false	Whether to show bootstrap results on focus before typing.
isDisabled	boolean	false	Whether the input is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label.
isReadOnly	boolean	false	Whether the input is read-only. Prevents typing and hides the clear button without applying disabled opacity.
label*	string	—	Field label.
labelIcon	IconComponent	—	Icon shown before the label.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
maxEntries	number	—	Maximum number of selected tags.
maxMenuItems	number	10	Maximum number of menu items.
onBlur	(event: FocusEvent<HTMLDivElement>) => void	—	Called when focus leaves the tags-input.
onChange*	(items: T[], change: TagsInputChange<T>) => void	—	Called when selected tags change.
onFocus	(event: FocusEvent<HTMLDivElement>) => void	—	Called when focus enters the tags-input.
onQueryChange	(query: string) => void	—	Called when the query changes.
placeholder	string	—	Placeholder text.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the field root.
renderItem	(item: T) => ReactNode	—	Custom result renderer.
renderTag	(item: T, onRemove: () => void) => ReactNode	—	Custom tag renderer.
searchSource*	SearchSource<T>	—	Provides results for the menu. Use createStaticSearchSource for in-memory data, or implement SearchSource for async/remote search.
size	"sm" | "md" | "lg"	'md'	Visual size.
startIcon	IconComponent	—	Icon shown before the input.
status	InputStatus	—	Validation status displayed below the tags-input.
style	CSSProperties	—	Inline styles applied to the input wrapper.
tagOverflowBehavior	"none" | "unfocusedInline" | "unfocusedLayer"	'none'	Controls how tags overflow when the container is too narrow. - 'none': Tags wrap to multiple lines (default). - 'unfocusedInline': Single line with "+ N more" when unfocused; expands inline on focus. - 'unfocusedLayer': Single line with "+ N more" when unfocused; expands as overlay on focus.
value*	T[]	—	Selected items.
isOptional*	true	—
isRequired	false	—
hasCreate	boolean	false	Whether users can create a tag from free text.
createItem	(rawValue: string) => T	—	Builds the committed item from the typed text. Optional for this item type because the default builder — rawValue => ({id: rawValue, label: rawValue}) — already produces a valid item. Builds the committed item from the typed text. Required for this item type because it has fields the default {id, label} builder cannot supply.

When isOptional: false, isRequired: true

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the input wrapper.
data-testid	string	—	Test ID applied to the input wrapper.
debounceMs	number	150	Debounce delay in milliseconds before search runs.
description	ReactNode	—	Supporting text rendered below the label.
emptySearchResultsText	string	'No results found'	Empty state text.
endContent	ReactNode	—	Content rendered at the end of the input row.
handleRef	Ref<TagsInputHandle>	—	Imperative focus/blur handle.
hasAutoFocus	boolean	false	Whether to focus the input on mount.
hasClear	boolean	false	Whether to show a clear button that removes all tags.
hasEntriesOnFocus	boolean	false	Whether to show bootstrap results on focus before typing.
isDisabled	boolean	false	Whether the input is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label.
isReadOnly	boolean	false	Whether the input is read-only. Prevents typing and hides the clear button without applying disabled opacity.
label*	string	—	Field label.
labelIcon	IconComponent	—	Icon shown before the label.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
maxEntries	number	—	Maximum number of selected tags.
maxMenuItems	number	10	Maximum number of menu items.
onBlur	(event: FocusEvent<HTMLDivElement>) => void	—	Called when focus leaves the tags-input.
onChange*	(items: T[], change: TagsInputChange<T>) => void	—	Called when selected tags change.
onFocus	(event: FocusEvent<HTMLDivElement>) => void	—	Called when focus enters the tags-input.
onQueryChange	(query: string) => void	—	Called when the query changes.
placeholder	string	—	Placeholder text.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the field root.
renderItem	(item: T) => ReactNode	—	Custom result renderer.
renderTag	(item: T, onRemove: () => void) => ReactNode	—	Custom tag renderer.
searchSource*	SearchSource<T>	—	Provides results for the menu. Use createStaticSearchSource for in-memory data, or implement SearchSource for async/remote search.
size	"sm" | "md" | "lg"	'md'	Visual size.
startIcon	IconComponent	—	Icon shown before the input.
status	InputStatus	—	Validation status displayed below the tags-input.
style	CSSProperties	—	Inline styles applied to the input wrapper.
tagOverflowBehavior	"none" | "unfocusedInline" | "unfocusedLayer"	'none'	Controls how tags overflow when the container is too narrow. - 'none': Tags wrap to multiple lines (default). - 'unfocusedInline': Single line with "+ N more" when unfocused; expands inline on focus. - 'unfocusedLayer': Single line with "+ N more" when unfocused; expands as overlay on focus.
value*	T[]	—	Selected items.
isOptional	false	—
isRequired*	true	—
hasCreate	boolean	false	Whether users can create a tag from free text.
createItem	(rawValue: string) => T	—	Builds the committed item from the typed text. Optional for this item type because the default builder — rawValue => ({id: rawValue, label: rawValue}) — already produces a valid item. Builds the committed item from the typed text. Required for this item type because it has fields the default {id, label} builder cannot supply.