Tangible Design System · @tangible/ui 0.2.29 · Markdown

Combobox

import { Combobox, useCombobox } from '@tangible/ui';

Combobox 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 button when a value is present.
defaultOpen? boolean false Default open state for uncontrolled usage.
defaultValue? OptionValue Default value for uncontrolled usage.
disabled? boolean false Whether the combobox is disabled.
filterMode? "always" | "when-searching" 'always' Controls filtering behavior. 'always': Filter on inputValue at all times (default); 'when-searching': Query is empty when not actively typing, so consumers can show all options when user is browsing a selection
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? ComboboxLabels Override default English strings for i18n.
onInputChange? (value: string) => void Callback when input value changes (typing, clear).
onOpenChange? (open: boolean) => void Callback when open state changes.
onQueryChange? (query: string) => void Callback when the effective query changes. Query differs from inputValue when filterMode='when-searching': it becomes empty after selection to show all options.
onValueChange? (value: OptionValue | undefined) => void Callback when selection changes. Called with the option's value when user selects, or undefined when cleared. Does NOT mutate inputValue — consumer should update inputValue in handler if desired.
open? boolean Controlled open state.
openOnFocus? boolean true Whether to open the listbox when the input receives focus.
placeholder? string '' Placeholder text for the input.
size? "lg" | "md" | "sm" 'md' Control size.
value? OptionValue Controlled selected value.

Combobox.Content

Also exported as ComboboxContent.

Prop Type Default Description
children React.ReactNode
className? string Additional CSS class names.

Combobox.Option

Also exported as ComboboxOption.

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 Additional CSS class names.
disabled? boolean false Whether this option is disabled.
textValue? string Text value used for display when selected. Required when children is not a string. If children is a string, defaults to that.

Combobox.Group

Also exported as ComboboxGroup.

Prop Type Default Description
children? ReactNode
className? string

Combobox.Label

Also exported as ComboboxLabel.

Prop Type Default Description
children? ReactNode
className? string

Hooks

useCombobox

useCombobox(): ComboboxActionsContextValue & ComboboxStateContextValue

Returns:

Member Type Description
disabled boolean
placeholder string
openOnFocus boolean
inputId string
listboxId string
ariaLabel? string
ariaLabelledBy? string
setOpen (open: boolean) => void
setInputValue (value: string) => void
selectOption (value: OptionValue) => 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>
wrapperRef RefObject<HTMLDivElement | null> The field box (.tui-combobox__input-wrapper) — the input-group host. Content anchors the portal root and the panel's min-width to it, not to the input, which is inset by the group's padding.
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 OptionValue | undefined
inputValue string
query string The effective query to filter on. When filterMode='when-searching', this is empty after selection (allowing all options to show). Otherwise equals inputValue.
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

Component API tokens

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