Tangible Design System · @tangible/ui 0.2.29 · Interactive version · Markdown

MultiCombobox

import { MultiCombobox, useMultiCombobox } from '@tangible/ui';

Interactive docs and examples: MultiCombobox in Storybook.

MultiCombobox props

Prop Type Default Description
children React.ReactNode
aria-describedby? string ID(s) of element(s) that describe this combobox (helper text, error). Forwarded to the input — Field.Control injects this.
aria-invalid? "false" | "true" | boolean Invalid state, forwarded to the input. Field.Control injects this.
aria-label? string Accessible name for the combobox.
aria-labelledby? string ID of element that labels this combobox.
aria-required? "false" | "true" | boolean Required state, forwarded to the input. Field.Control injects this.
clearable? boolean true Whether to show the clear-all button when values are present.
defaultOpen? boolean false Default open state for uncontrolled usage.
defaultValue? MultiComboboxValue Default values for uncontrolled usage.
disabled? boolean false Whether the combobox is disabled.
filterMode? "always" | "when-searching" 'always' Controls filtering behavior.
id? string Optional input ID override, applied to the inner <input>. Useful for Field integration via htmlFor — Field.Control injects this.
inputClassName? string Class name applied directly to the <input> element. Use for utilities like tui-input-reset that must target the input itself.
inputValue? string Controlled input value for search/filter.
labels? MultiComboboxLabels Override default English strings for i18n.
max? number Maximum number of selections allowed. When reached, unselected options become disabled.
onInputChange? (value: string) => void Callback when input value changes (typing, clear).
onMaxReached? () => void Callback when max selections is reached.
onOpenChange? (open: boolean) => void Callback when open state changes.
onQueryChange? (query: string) => void Callback when the effective query changes.
onValueChange? (value: MultiComboboxValue) => void Callback when selection changes.
open? boolean Controlled open state.
openOnFocus? boolean true Whether to open the listbox when the input receives focus.
overflow? "trim" | "wrap" 'trim' How selected chips behave when they exceed the control width. 'trim' (default): the control stays a single line (fixed height); chips flow horizontally and clip toward the inline-start, keeping the typing area in view. Preserves row alignment in multi-column form layouts. 'wrap': chips wrap onto new lines and the control grows vertically. Opt in for standalone or spacious placements.
placeholder? string '' Placeholder text for the input. Shown only when no values are selected.
size? "lg" | "md" | "sm" 'md' Control size.
value? MultiComboboxValue Controlled selected values.

MultiCombobox.Content

Also exported as MultiComboboxContent.

Prop Type Default Description
children React.ReactNode
className? string

MultiCombobox.Option

Also exported as MultiComboboxOption.

Prop Type Default Description
children React.ReactNode
value OptionValue The value for this option. Required and must be unique. Can be string or number.
className? string
disabled? boolean false Whether this option is disabled.
textValue? string Text value used for the chip label when selected. Required when children is not a string. If children is a string, defaults to that.

MultiCombobox.Group

Also exported as MultiComboboxGroup.

Prop Type Default Description
children? ReactNode
className? string

MultiCombobox.Label

Also exported as MultiComboboxLabel.

Prop Type Default Description
children? ReactNode
className? string

Hooks

useMultiCombobox

useMultiCombobox(): MultiComboboxActionsContextValue & MultiComboboxStateContextValue

Returns:

Member Type Description
disabled boolean
placeholder string
openOnFocus boolean
max number | undefined
inputId string
listboxId string
ariaLabel? string
ariaLabelledBy? string
setOpen (open: boolean) => void
setInputValue (value: string) => void
toggleOption (value: OptionValue, textValue: string) => void
registerOption (option: RegisteredOption) => void
unregisterOption (value: OptionValue) => void
refs { reference: React.RefObject<ReferenceType | null>; floating: React.RefObject<HTMLElement | null>; setReference: (node: ReferenceType | null) => void; setFloating: (node: HTMLElement | null) => void; }
inputRef RefObject<HTMLInputElement | null>
listRef MutableRefObject<(HTMLElement | null)[]>
getReferenceProps (userProps?: React.HTMLProps<Element>) => Record<string, unknown>
getFloatingProps (userProps?: React.HTMLProps<HTMLElement>) => Record<string, unknown>
getItemProps (userProps?: React.HTMLProps<HTMLElement>) => Record<string, unknown>
open boolean
value MultiComboboxValue
inputValue string
maxReached boolean
isSelected (value: OptionValue) => boolean
query string
activeIndex number
activeOptionId string | undefined
orderedOptions RegisteredOption[]
floatingStyles CSSProperties
floatingContext FloatingContext

RegisteredOption (the option of registerOption):

Member Type Description
value OptionValue
ref RefObject<HTMLElement | null>
disabled boolean
textValue string

Examples

Stories: Basic, Initial Values, Max (3), Sizes, Overflow: trim, Async, With Field, Disabled (interactive page).

Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.