# Combobox **An input with a popup list for searching and selecting values from a collection.** **Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/Combobox) · [Zag.js Docs](https://zagjs.com/components/react/combobox) **ComboboxExamples.html** ```html Select a city No cities found. {item.label} ``` ## Features - Searchable list with keyboard navigation - Single and multiple selection - Disabled items and item groups - Works with the Field component for forms and validation - Submits the `value` of the selected items through `hiddenInput`, the visible input shows their labels - `empty` placeholder for a search without matches - Locale-aware filtering in the default entry file, replaceable per instance through `onInputValueChange` - Async, server-rendered search results via `ui:template` - `dialog` popup type moves the input into the popup, behind a focusable trigger ## Anatomy `hiddenInput` submits the `value` of the selected items. Place it once anywhere inside `combobox.root` and it renders one visually hidden input per selected value, or a single empty one while nothing is selected. `ui:combobox.root` includes it for you. A [Field](/docs/components/field.md) focuses the combobox through that input when it is the first invalid field of a submitted form, and the input hands the focus on to the visible one. Place the options inside `list`, which carries the listbox semantics and scrolling. `content` wraps it and is announced as a dialog with the `dialog` popup type. The styled `ui:combobox.content` combines `positioner` and `content` in one part, so you nest `ui:combobox.list` in it yourself. `combobox.empty` is a placeholder for a collection with nothing to show, because no item matches the search text or an async search is still waiting for results. Place it next to `combobox.list` inside `content`. It shows and hides itself. ```html ``` ## Installation ```bash typo3 ui:add combobox ``` Or copy the files manually from GitHub (https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Registry/Combobox) into your project. Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md). ## Examples ### Default value Pass `defaultValue` to preselect an item. The demo opens with Nigeria in the input, rendered on the server. **ComboboxExamples.html** ```html Country No countries found. {item.label} ``` ### Disabled items Set `disabled: true` on an item of the collection to make it unselectable. Oracle Database and Microsoft SQL Server are disabled in the demo. **ComboboxExamples.html** ```html Select a database No databases found. {item.label} ``` ### With item groups Set `groupByKey` on `ui:listCollection` to group the items, here by their `category`. Type in the demo and groups without a match disappear. **ComboboxExamples.html** ```html Search technologies No technologies found. {groupName} {item.label} ``` ### With form field Wrap the combobox in `ui:field.root` to share label, `name`, required and invalid state. The demo is a required country field. **ComboboxExamples.html** ```html Country No countries found. {item.label} This description comes from the field primitive. ``` ### Multiple selection Set `multiple="{true}"` to select several values. The demo lists the selected cities above the input. **ComboboxExamples.html** ```html
Select destinations No cities found. {item.label} ``` ### Change the filter Pass your own `onInputValueChange` in a custom entry file to change how items match, here by the start of the label with `startsWith`. Type "b" in the demo and the list shrinks to the cities starting with B. **ComboboxExamples.html** ```html Starts-with filter
Uses a custom mount entry with its own `onInputValueChange` filter (starts-with instead of contains).
No cities found. {item.label} ``` ### Async search Fetch matching items from a server-side search endpoint as people type. Type a city in the demo to see the results come in. Write the item markup once inside a [`ui:template`](/docs/viewhelpers/template.md) block and pass the endpoint as `searchUrl`. The entry file queries it, clones the template for every result and rebuilds the collection. `combobox.item`, `combobox.itemText` and `combobox.itemIndicator` detect the template on their own, so they take no `value`. `collection` is optional when no items are known up front. `combobox.empty` shows whenever no item is rendered: before the first query, while a request runs, after an error and for a query without matches. Its content is yours to update, here a spinner and a status text. They are slot content, so their `ui:ref` takes `context: 'combobox'`, as in `{ui:ref(name: 'statusSpinner', context: 'combobox')}`. The demo sends the query with [`extbase.post()`](/docs/client-utilities/extbase.md), fetches with [`AsyncList`](/docs/client-utilities/async-list.md) and delays the spinner with a [`DelayedIndicator`](/docs/client-utilities/delayed-indicator.md) to avoid flicker on fast responses. **ComboboxExamples.html** ```html Search for a city
Items are fetched from a search endpoint.
Start typing to search… ``` **AsyncSearch.entry.ts** ```ts import type { Api as AsyncListApi } from '@zag-js/async-list'; import type { CollectionItem } from '@zag-js/collection'; import { ListCollection } from '@zag-js/collection'; import type { InputValueChangeDetails } from '@zag-js/combobox'; import { debounce } from '@zag-js/utils'; import { AsyncList, DelayedIndicator, extbase, mount, Template } from 'fluid-primitives'; import { Combobox } from 'fluid-primitives/combobox'; interface CityResult extends CollectionItem { value: string; title: string; description?: string; } const SEARCH_DEBOUNCE_MS = 300; type SearchStatus = 'loading' | 'error' | 'empty' | 'idle' | 'results'; const STATUS_TEXT: Record, string> = { loading: 'Searching…', error: 'Something went wrong. Please try again.', empty: 'No results found', idle: 'Start typing to search…', }; // The item list is folded into the same value the status placeholder is driven by, rather than // updated separately and immediately from the raw subscribe callback - otherwise the old items // would be removed the instant a new search starts (api.isLoading flips true) while the "Searching…" // placeholder stays hidden for its own showDelayMs, leaving a visible gap with nothing rendered // in between. Routing both through one DelayedIndicator means the old items only ever disappear // at the exact moment something else is ready to take their place - fresh results immediately, or // the placeholder once it's actually shown. type SearchState = | { status: 'loading' } | { status: 'error' } | { status: 'empty' } | { status: 'idle' } | { status: 'results'; items: CityResult[] }; function getSearchState(api: AsyncListApi): SearchState { const hasResults = !api.isLoading && !api.error && !api.isEmpty; if (hasResults) return { status: 'results', items: api.items }; if (api.isLoading) return { status: 'loading' }; if (api.error) return { status: 'error' }; return api.filter.trim() ? { status: 'empty' } : { status: 'idle' }; } mount('ui:combobox', 'async-search', ({ props }) => { const searchUrl = props.searchUrl as string; let insertedItems: HTMLElement[] = []; let combobox: Combobox; function updateItems(items: CityResult[]) { const listEl = combobox.hydrator.query('list'); if (!listEl) return; insertedItems.forEach(el => el.remove()); insertedItems = []; const collection = new ListCollection({ items, itemToValue: item => item.value, itemToString: item => item.title, }); for (const { value, title, description } of collection) { const instance = new Template(combobox.hydrator, 'itemTemplate', { value }); const titleEl = instance.query('title'); if (titleEl) titleEl.textContent = title; const descriptionEl = instance.query('description'); if (description) { if (descriptionEl) descriptionEl.textContent = description; } else { descriptionEl?.remove(); } listEl.appendChild(instance); insertedItems.push(instance.root); } combobox.updateProps({ collection }); } // Renders both the item list and the status placeholder from one incoming state, so the two // are always in sync - old items and the old status text/spinner only ever change together, // at the moment DelayedIndicator decides something new is actually ready to be shown. const searchState = new DelayedIndicator({ isTransient: s => s.status === 'loading', onChange: state => { const spinnerEl = combobox.hydrator.query('statusSpinner'); const textEl = combobox.hydrator.query('statusText'); if (!spinnerEl || !textEl) return; const hasResults = state.status === 'results'; updateItems(hasResults ? state.items : []); if (hasResults) return; spinnerEl.toggleAttribute('hidden', state.status !== 'loading'); textEl.textContent = STATUS_TEXT[state.status]; }, }); const list = new AsyncList({ load: async ({ signal, filter }) => { if (!filter.trim()) return { items: [] as CityResult[] }; // post() namespaces { q: filter } under searchUrl's own tx_docs_docs[...] // prefix automatically and sends it as a POST body, sidestepping the cHash mismatch // a GET query param appended after the fact would otherwise cause (f:uri.action's // cHash is computed from the arguments known at build time). const response = await extbase.post(searchUrl, { q: filter }, { signal }); if (!response.ok) { throw new Error(`City search failed with status ${response.status}`); } return { items: (await response.json()) as CityResult[] }; }, }); list.subscribe(api => { searchState.set(getSearchState(api)); }); // Debounced here rather than inside AsyncList itself - a plain wrap of setFilter, the // same way you'd debounce any other callback. const setFilterDebounced = debounce( (filter: string) => list.setFilter(filter), SEARCH_DEBOUNCE_MS ); combobox = new Combobox({ ...props, onInputValueChange: (details: InputValueChangeDetails) => { if (details.reason === 'input-change') setFilterDebounced(details.inputValue); }, }); list.init(); combobox.init(); return combobox; }); ``` ### Async search with groups Group the results the endpoint returns, here by country. Write a second `ui:template` for the group (`combobox.itemGroup` with `combobox.itemGroupLabel`), clone it once per group, append the cloned items to the group and the group to `combobox.list`. Pass the group key as the `value` of its [`Template`](/docs/client-utilities/template.md) so the groups stay apart. **ComboboxExamples.html** ```html Search for a city
Items are fetched from a search endpoint.
Start typing to search… ``` **AsyncSearchGrouped.entry.ts** ```ts import type { Api as AsyncListApi } from '@zag-js/async-list'; import type { CollectionItem } from '@zag-js/collection'; import { ListCollection } from '@zag-js/collection'; import type { InputValueChangeDetails } from '@zag-js/combobox'; import { debounce } from '@zag-js/utils'; import { AsyncList, DelayedIndicator, extbase, mount, Template } from 'fluid-primitives'; import { Combobox } from 'fluid-primitives/combobox'; interface CityResult extends CollectionItem { value: string; title: string; description?: string; } const SEARCH_DEBOUNCE_MS = 300; type SearchStatus = 'loading' | 'error' | 'empty' | 'idle' | 'results'; const STATUS_TEXT: Record, string> = { loading: 'Searching…', error: 'Something went wrong. Please try again.', empty: 'No results found', idle: 'Start typing to search…', }; // The group/item list is folded into the same value the status placeholder is driven by, rather // than updated separately and immediately from the raw subscribe callback - otherwise the old // groups would be removed the instant a new search starts (api.isLoading flips true) while the // "Searching…" placeholder stays hidden for its own showDelayMs, leaving a visible gap with // nothing rendered in between. Routing both through one DelayedIndicator means the old groups // only ever disappear at the exact moment something else is ready to take their place - fresh // results immediately, or the placeholder once it's actually shown. type SearchState = | { status: 'loading' } | { status: 'error' } | { status: 'empty' } | { status: 'idle' } | { status: 'results'; items: CityResult[] }; function getSearchState(api: AsyncListApi): SearchState { const hasResults = !api.isLoading && !api.error && !api.isEmpty; if (hasResults) return { status: 'results', items: api.items }; if (api.isLoading) return { status: 'loading' }; if (api.error) return { status: 'error' }; return api.filter.trim() ? { status: 'empty' } : { status: 'idle' }; } mount('ui:combobox', 'async-search-grouped', ({ props }) => { const searchUrl = props.searchUrl as string; let insertedGroups: HTMLElement[] = []; let combobox: Combobox; function updateItems(items: CityResult[]) { const listEl = combobox.hydrator.query('list'); if (!listEl) return; insertedGroups.forEach(el => el.remove()); insertedGroups = []; // Grouping by country is baked into the collection itself (groupBy/groupSort), the same // way the static "With Item Groups" example groups server-side via groupByKey/groupSort - // group() then just reads back what the collection already grouped/sorted. const collection = new ListCollection({ items, itemToValue: item => item.value, itemToString: item => item.title, groupBy: item => item.description || 'Other', groupSort: 'asc', }); for (const [country, countryItems] of collection.group()) { // The group's own key doubles as its restamp value - stable and unique per group // (unlike a random uid()), and what Combobox's own render() needs to correctly link // each group's content/label pair via id/aria-labelledby (spreadPropsByValue('itemGroup', ...)). const group = new Template(combobox.hydrator, 'groupTemplate', { value: country }); const labelEl = group.query('group-label'); if (labelEl) labelEl.textContent = country; for (const { value, title } of countryItems) { const item = new Template(combobox.hydrator, 'itemTemplate', { value }); const titleEl = item.query('title'); if (titleEl) titleEl.textContent = title; group.root.appendChild(item); } listEl.appendChild(group); insertedGroups.push(group.root); } combobox.updateProps({ collection }); } // Renders both the group/item list and the status placeholder from one incoming state, so // the two are always in sync - old groups and the old status text/spinner only ever change // together, at the moment DelayedIndicator decides something new is actually ready to be shown. const searchState = new DelayedIndicator({ isTransient: s => s.status === 'loading', onChange: state => { const spinnerEl = combobox.hydrator.query('statusSpinner'); const textEl = combobox.hydrator.query('statusText'); if (!spinnerEl || !textEl) return; const hasResults = state.status === 'results'; updateItems(hasResults ? state.items : []); if (hasResults) return; spinnerEl.toggleAttribute('hidden', state.status !== 'loading'); textEl.textContent = STATUS_TEXT[state.status]; }, }); const list = new AsyncList({ load: async ({ signal, filter }) => { if (!filter.trim()) return { items: [] as CityResult[] }; // post() namespaces { q: filter } under searchUrl's own tx_docs_docs[...] // prefix automatically and sends it as a POST body, sidestepping the cHash mismatch // a GET query param appended after the fact would otherwise cause (f:uri.action's // cHash is computed from the arguments known at build time). const response = await extbase.post(searchUrl, { q: filter }, { signal }); if (!response.ok) { throw new Error(`City search failed with status ${response.status}`); } return { items: (await response.json()) as CityResult[] }; }, }); list.subscribe(api => { searchState.set(getSearchState(api)); }); // Debounced here rather than inside AsyncList itself - a plain wrap of setFilter, the // same way you'd debounce any other callback. const setFilterDebounced = debounce( (filter: string) => list.setFilter(filter), SEARCH_DEBOUNCE_MS ); combobox = new Combobox({ ...props, onInputValueChange: (details: InputValueChangeDetails) => { if (details.reason === 'input-change') setFilterDebounced(details.inputValue); }, }); list.init(); combobox.init(); return combobox; }); ``` ### Move the input into the popup Set `popupType="{f:constant(name: 'Jramke\FluidPrimitives\Enum\PopupType::Dialog')}"` for a popover-style picker: a trigger opens the popup and the `input` sits at the top of the `content`, above the `list`. `content` is announced as a dialog, and the trigger is focusable (its own `focusable` prop overrides that). With the input in the popup, the trigger shows the selection itself, here through a `valueText` element the entry file keeps in sync with `api.valueAsString`. Open the picker in the demo and type to filter. **ComboboxExamples.html** ```html Select a city Choose a city No cities found. {item.label} ``` **InputInContent.entry.ts** ```ts import type { InputValueChangeDetails } from '@zag-js/combobox'; import { createFilter } from '@zag-js/i18n-utils'; import { getGlobal, mount } from 'fluid-primitives'; import { Combobox } from 'fluid-primitives/combobox'; const filter = createFilter({ sensitivity: 'base', locale: getGlobal('locale') }); mount('ui:combobox', 'input-in-content', ({ props }) => { const combobox = new Combobox({ ...props, // The trigger shows the selection, so the input starts empty every time the popup opens. onOpenChange: ({ open }) => { if (!open) combobox.api.setInputValue(''); }, onInputValueChange: (details: InputValueChangeDetails) => { const source = combobox.getSourceCollection(); if (details.reason !== 'input-change') { combobox.updateProps({ collection: source }); return; } const query = details.inputValue.trim(); combobox.updateProps({ collection: query ? source.filter(itemString => filter.contains(itemString, query)) : source, }); }, }); combobox.init(); // The input lives in the popup, so the trigger has to show the selection itself. const valueTextEl = combobox.hydrator.query('valueText'); if (valueTextEl) { const placeholder = valueTextEl.textContent ?? ''; combobox.machine.subscribe(() => { const { valueAsString } = combobox.api; valueTextEl.textContent = valueAsString || placeholder; valueTextEl.classList.toggle('text-muted-foreground', !valueAsString); }); } return combobox; }); ``` ### Localization The labels of the trigger and the clear button ship in the language file and follow the site language. Pass `translations` to override them for one combobox. ```html ... ``` ## API Reference ### combobox.root Provides shared combobox state and wraps all related parts. Renders a `
` element. | Name | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `collection` | `Domain\Dto\ListCollection` | Yes | `-` | The item collection. | | `name` | `string` | No | `-` | The `name` attribute of the underlying select. Inherited from a surrounding field when available. | | `form` | `string` | No | `-` | The associate form of the underlying select. | | `disabled` | `boolean` | No | `-` | Whether the select is disabled. Inherited from a surrounding field when available. | | `invalid` | `boolean` | No | `-` | Whether the select is invalid. Inherited from a surrounding field when available. | | `readOnly` | `boolean` | No | `-` | Whether the select is read-only. Inherited from a surrounding field when available. | | `required` | `boolean` | No | `-` | Whether the select is required. Inherited from a surrounding field when available. | | `placeholder` | `string` | No | `-` | The placeholder text of the combobox's input. | | `defaultOpen` | `boolean` | No | `false` | The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox. | | `defaultValue` | `mixed` | No | `-` | The initial value of the combobox's selected items when rendered. Use when you don't need to control the value of the combobox's selected items. | | `defaultInputValue` | `string` | No | `-` | The initial value of the combobox's input when rendered. Use when you don't need to control the value of the combobox's input. | | `defaultHighlightedValue` | `string` | No | `-` | The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox. | | `openOnClick` | `boolean` | No | `false` | Whether to open the combobox popup on initial click on the input. | | `openOnKeyPress` | `boolean` | No | `true` | Whether to open the combobox on arrow key press. | | `openOnChange` | `boolean` | No | `true` | Whether to show the combobox when the input value changes. | | `closeOnSelect` | `boolean` | No | `-` | Whether to close the combobox when an item is selected. Defaults to `true` or if multiple enabled `false`. | | `loopFocus` | `boolean` | No | `true` | Whether to loop focus within the combobox. | | `multiple` | `boolean` | No | `-` | Whether to allow multiple selection. **Good to know:** When `multiple` is `true`, the `selectionBehavior` is automatically set to `clear`. It is recommended to render the selected items in a separate container. | | `allowCustomValue` | `boolean` | No | `false` | Whether to allow typing custom values in the input. | | `alwaysSubmitOnEnter` | `boolean` | No | `false` | Whether to always submit on Enter key press, even if popup is open. Useful for single-field autocomplete forms where Enter should submit the form. | | `inputBehavior` | `Enum\ComboboxInputBehavior` | No | `None` | Defines the auto-completion behavior of the combobox. - `autohighlight`: The first focused item is highlighted as the user types - `autocomplete`: Navigating the listbox with the arrow keys selects the item and the input is updated. | | `selectionBehavior` | `Enum\ComboboxSelectionBehavior` | No | `-` | The behavior of the combobox input when an item is selected - `replace`: The selected item string is set as the input value - `clear`: The input value is cleared - `preserve`: The input value is preserved. Defaults to `replace` or if multiple enabled `clear` | | `popupType` | `Enum\PopupType` | No | `Listbox` | The kind of popup the combobox's content is: `listbox` for a regular combobox, `dialog` when it holds other interactive content. | | `autoFocus` | `boolean` | No | `-` | Whether to autofocus the input on mount. | | `positioning` | `array` | No | `{ "placement": "bottom", "sameWidth": true }` | The positioning options to dynamically position the menu. | | `translations` | `array` | No | `-` | Localized combobox labels. Use `f:translate` for per-template localization overrides when needed. | | `searchUrl` | `string` | No | `-` | Endpoint queried for async search results (e.g. built with f:uri.action in the consuming template). The consumer's own controller/entry.ts owns the request/response shape. | | `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. | | `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. | | `rootId` | `string` | No | `-` | The root ID of the component, used for hydration and identification. | | `ids` | `array` | No | `[]` | The IDs of of the component parts for composition. | | `autoMount` | `boolean` | No | `true` | Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()` | | `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. | #### Rendered data attributes | Attribute | Description | | --- | --- | | `data-combobox-root` | | | `data-invalid` | Present when invalid | | `data-readonly` | Present when read-only | ### combobox.label Labels the combobox. Renders a `