Components

Combobox

Choose one or several options from a list narrowed by typing; supports server results and adding new options.

Storybook: Storybook
Source: Source

Installation

Package: @bigbang/ui
Import: import { Combobox } from '@bigbang/ui';
Source: Combobox.tsx
Storybook: Combobox · Playground

Combobox is in the @bigbang/ui package. The option type is exported as ComboboxItem.

import { Combobox, type ComboboxItem } from '@bigbang/ui';

<Combobox label="City" items={items} value={city} onValueChange={setCity} />;

<Combobox multiple label="City" items={items} value={cities} onValueChange={setCities} />;

Props

multiple

Description: Allows several choices, shown as removable chips in the field.
Type: boolean
Default: false

value

Description: The chosen value when you control it; null for none. Use it with onValueChange.
Type: string | readonly string[] | null

defaultValue

Description: The chosen value on first render when you do not control it.
Type: string | readonly string[] | null

onValueChange

Description: Called with the new value when the user chooses or clears.
Type: ((value: string | null) => void) | ((value: string[]) => void)

labelRequired

Description: The visible label, bound to the input. A placeholder does not replace it.
Type: string

itemsRequired

Description: The options, or groups of options under headings ({ label, items }); a group with no match is hidden. For server results, pass the current page of results and set filter to false.
Type: readonly ComboboxItem[] | readonly ComboboxItemGroup[]

placeholder

Description: Text in the empty input, such as "Ara" or "Search".
Type: string

description

Description: Help text under the field, linked with aria-describedby before the error.
Type: ReactNode

error

Description: When set, the field is invalid and the message is read with the input.
Type: string

required

Description: A choice is required: the label gets * with a visually hidden "zorunlu" or "required".
Type: boolean
Default: false

disabled

Description: Disables the field and its label; the value is not submitted.
Type: boolean
Default: false

size

Description: Field height: 32, 36 or 40 px, as TextInput. With multiple the field grows as chips wrap.
Type: 'sm' | 'md' | 'lg'
Default: 'md'

name

Description: Field name used when the form is submitted.
Type: string

filter

Description: Filters items by the typed text, ignoring case in the Provider's language. Set false when the server filters.
Type: boolean
Default: true

onInputValueChange

Description: Called with the typed text; use it to load server results.
Type: (text: string) => void

loading

Description: Shows a loading row in the list and announces it, while server results load.
Type: boolean
Default: false

onCreate

Description: Lets the user add an option that is not in the list: an "Add …" row appears when the text matches no label. Return the new item; it is chosen at once. Add it to items too so it stays in the list.
Type: (label: string) => ComboboxItem

showClear

Description: Shows a clear button while a value is chosen; it takes the chevron's place. Without it, clear the text or remove chips to empty the field.
Type: boolean
Default: false

emptyText

Description: Text when nothing matches. Defaults to "Sonuç bulunamadı" or "No results" from the Provider.
Type: string

className

Description: Added to the root element; use it for layout only.
Type: string

material

Description: 'solid' keeps the list solid under a glass Provider. The field itself is always solid.
Type: 'auto' | 'solid'
Default: 'auto'

ComboboxItem: value, label, optional icon and disabled. value, defaultValue and onValueChange use string | null for a single choice and string[] with multiple.

Data attributes

data-component="combobox": on the root (Field).
data-part="control", "chip", "clear", "trigger", "popup", "item": on the parts.
data-popup-open, data-highlighted, data-selected: Base UI states.
data-part: group, group-label (with grouped items). The ComboboxItemGroup type is exported.