# nord-combobox > Combobox lets users choose one option (or several) from a list by typing to > filter, then picking with the keyboard or pointer. Use it when a Select > would be unwieldy because there are many options to scan. > > Combobox is a control only — it has no built-in label, hint or error. Compose > it inside a Field to give it a label, hint and error > message, the same way you would a native input. > > The committed value is an option's value (or an array of them with > multiple); the input is a filter/search field whose text is discarded on > commit. For a free-text input with suggestions where the typed text is the > value, use Autocomplete instead. ## Usage Combobox is a **control only** — it has no built-in label, hint or error. Pair it with a [Field](/components/field/) to give it a label, helper text and an error message, exactly like a native input. Connect the [Field Label](/components/field-label/) to the combobox with the `for` attribute so it gets an accessible name and click-to-focus. Import the combobox and the Field parts you need — each import registers its custom element: ```js import '@nordhealth/components/lib/Combobox' import '@nordhealth/components/lib/Field' import '@nordhealth/components/lib/FieldLabel' import '@nordhealth/components/lib/FieldDescription' import '@nordhealth/components/lib/FieldError' ``` Then compose the Field around the combobox: ```html Framework Choose the framework for your project. ``` Provide the choices with the `options` property — pairing it with a Field only handles labelling and layout, it doesn't change how you populate the list: ```js document.querySelector('nord-combobox').options = [ { value: 'next', label: 'Next.js' }, { value: 'astro', label: 'Astro' }, ] ``` Combobox renders in the light DOM, so you can style it directly with your own CSS or Tailwind utilities, and set its width on the combobox (or on its Field). Use the `size` property (`s`, `m` or `l`, defaulting to `m`) to scale the control's height, padding and font size to match surrounding form controls. ### Select vs free-text suggestions The committed `value` is an option's `value`. The input is a search/filter field whose text is discarded on commit; closing the listbox reverts the input to the selected option's label. Nothing is committed unless the user picks an option, so the value is always one of the options you provide (or an array of them with `multiple`). If you instead need the typed text *itself* to be the committed value — free-text input with the options as completion aids — use [Autocomplete](/components/autocomplete/). Autocomplete also offers `inline` ghost-text completion, where arrow-key navigation previews the highlighted option's remaining label. ### Picking an option vs creating one Both `multiple` and `creatable` keep the `value` made of option `value`s — they never produce arbitrary free text (use [Autocomplete](/components/autocomplete/) for that): - **`multiple`** lets users pick several options, each shown as a removable chip; the listbox stays open after every selection. - **`creatable`** offers a *Create* row (hinted with a ⏎ Kbd) when the query matches no option. Choosing it fires a `create` event so **you** add the option — the combobox never mutates `options`. With `multiple`, append the created option to `value` yourself. The inner input always hard-codes `autocomplete="off"` so browser autofill never fights the suggestion list. > **Do:** - Use when users need to pick from a long list of options and benefit from typing to filter, such as countries, timezones or frameworks. - Pair it with a [Field](/components/field/) and a [Field Label](/components/field-label/) connected with `for`, so it has an accessible name, helper text and an error message. - Use `multiple` when users may legitimately pick more than one option, showing each choice as a removable chip. - Use `external-filtering` and update `options` from the `input` event when the list comes from a server or is too large to filter on the client. - Group related options with the `group` property to help users scan long lists. > **Don't:** - Don’t use when there are only a handful of options and filtering adds no value, see [Select](/components/select/) instead. - Don’t add a Field Label without a `for` pointing at the combobox’s `id`, or the control will have no accessible name. - Don’t use for free-form text entry, see [Input](/components/input/) instead. - Don’t use to trigger actions or commands, see [Command Menu](/components/command-menu/) instead. ## Examples ### Basic ```html Framework ``` ### With Start End Slots ```html Framework ``` ### Multiple ```html Frameworks ``` ### Groups ```html Timezone ``` ### Creatable ```html Tag bug feature docs Type a new tag, then press Enter to create it ``` ### Declarative ```html Framework Next.js SvelteKit Nuxt.js Astro Timezone (GMT-5) New York (GMT-8) Los Angeles (GMT+0) London (GMT+1) Paris ``` ### Declarative Custom Items ```html Assignee Ada Lovelace Grace Hopper ``` ### Async ```html User ``` ### Async Multiple ```html Users ``` ### Virtualized ```html Option ``` ### Clear Button ```html Country ``` ### Auto Highlight ```html Country The first match is highlighted — press Enter to select it ``` ### Invalid ```html Country Please choose a country. ``` ### Readonly ```html Country ``` ### Disabled ```html Country ``` ### R T L ```html نوع الحيوان ``` ### Custom Items ```html Assignee ``` ### Disabled Items ```html Framework ``` ### Open On Input Click Off ```html Framework ``` ### Inside Dialog ```html Open dialog

Choose a framework

Framework Done ``` ### Input Group ```html Country Apply ``` ### Popup ```html Country Choose your country of residence ``` ### Standalone ```html Next.js Nuxt Astro ``` ### Field ```html Framework Next.js Nuxt Astro Pick your stack. ``` ## API Reference ### Properties - **value** (`string`, default: `''`) — The value of the combobox. A single string when multiple is false, or an array of strings when multiple is true. - **multiple** (`boolean`, default: `false`) — Allows selecting more than one option. Selected options are shown as removable chips and the listbox stays open after each selection. - **clearable** (`boolean`, default: `true`) — Shows a clear (✕) button while there is a value. Pressing it resets the value to '' (or [] when multiple), then fires clear and change. Defaults to true. This prop only toggles the button. A single-select value can always be cleared by deleting the input text, regardless of this prop (Base UI parity). - **creatable** (`boolean`, default: `false`) — Offers a "Create" affordance when the query does not exactly match an existing option. Choosing it (click or Enter) adds the typed value as an option and selects it (in multiple mode it is appended as a chip), and fires a cancelable create event. Call event.preventDefault() to opt out and handle creation yourself (e.g. to map the value to a different value). - **size** (`'s' | 'm' | 'l'`, default: `'m'`) — The size of the component. - **autocomplete** (`AutocompleteAttribute`, default: `'off'`) — Specifies the data type of the field, so that the browser may attempt to fill out the field automatically on behalf of the user. - **label** (`string`, default: `''`) — Label for the control. Ignored when the control is wrapped in a <nord-field>, which provides the label via <nord-field-label>. - **hint** (`string | undefined`) — Optional hint text shown with the control. Ignored inside a <nord-field>, which provides it via <nord-field-description>. - **hint-below** (`boolean`, default: `false`) — Renders the hint below the control and any error instead of below the label. - **hide-label** (`boolean`, default: `false`) — Visually hide the label, but still expose it to assistive technologies. - **error** (`string | undefined`) — Optional error shown with the control. Ignored inside a <nord-field>, which provides it via <nord-field-error>. - **required** (`boolean`, default: `false`) — Determines whether the control is required or not. A required control is announced as such to assistive technology and, inside a <nord-field>, drives the required indicator on the <nord-field-label>. When using this property you need to also set “novalidate” attribute on a form element to prevent browser from displaying its own validation errors. - **hide-required** (`boolean`, default: `false`) — Visually hide the required indicator, but still expose the required state to assistive technologies. - **disabled** (`boolean`, default: `false`) — Makes the component disabled. This prevents users from being able to interact with the component, and conveys its inactive state to assistive technologies. - **name** (`string | undefined`) — The name of the form component. - **form** (`HTMLFormElement | null`) — Gets the form, if any, associated with the form element. The setter accepts a string, which is the id of the form. - **open** (`boolean`, default: `false`) — Controls whether the component is open or not. - **align** (`'start' | 'end'`, default: `'start'`) — Set the alignment in relation to the toggle (or anchor) depending on the position. start will align it to the left of the toggle (or anchor). end will align it to the right of the toggle (or anchor). Setting the position to inline-start or inline-end will switch start and end to the top and bottom respectively. - **position** (`'block-end' | 'block-start' | 'inline-start' | 'inline-end' | 'auto'`, default: `'block-end'`) — Set the position in relation to the toggle (or anchor). Options follow logical properties. block-start and block-end referring to top and bottom respectively, inline-start and inline-end referring to left and right respectively. You can also set it to auto for automatic positioning depending on which side has the most space available. - **side-offset** (`number`, default: `8`) — Distance in pixels from the toggle (or anchor) along the main axis — the gap between the floating element and the side it opens against. Fed into Floating UI's offset middleware as mainAxis. Defaults to 8. - **align-offset** (`number`, default: `0`) — Offset in pixels along the alignment axis — slides the floating element toward the start or end of the toggle (or anchor). Fed into Floating UI's offset middleware as alignmentAxis. Defaults to 0. - **placeholder** (`string | undefined`) — Placeholder text to display within the input. - **external-filtering** (`boolean`, default: `false`) — Use external filtering mode. When set to true, the component will not perform internal text-based filtering and expects the consumer to update the options in response to the input event. - **loading** (`boolean`, default: `false`) — Shows a spinner in the control and listbox while asynchronous results are loading. Pair with external-filtering for async search. - **auto-highlight** (`boolean`, default: `false`) — Highlights the first option after filtering so pressing Enter selects it. - **invalid** (`boolean`, default: `false`) — Marks the control as invalid, applying error styling and setting aria-invalid on the input. - **readonly** (`boolean`, default: `false`) — Marks the control read-only: the value stays visible, focusable and submitted with the form, but the listbox can't be opened and the value can't be changed (no typing, navigation, selection or clearing). Unlike disabled, a read-only control still participates in form submission. - **open-on-input-click** (`boolean`, default: `true`) — Whether clicking the input opens the listbox. Defaults to true. Set to false to only open on typing or a trigger (chevron) click. Focusing the input (e.g. tabbing in) never opens the list on its own. Mirrors Base UI's openOnInputClick. - **no-results-text** (`string | undefined`) — Message shown when no options match the query. Defaults to "No items found.". - **virtualized** (`boolean`, default: `false`) — Virtualizes (windows) the option list so only the rows in view are rendered, keeping very large lists (thousands of options) fast. Rows are assumed to be a uniform height, which is measured from the first option. Virtualization is skipped for grouped lists, whose labels and separators break that assumption — grouped lists are expected to be short and curated. ### Events - **change** (`NordEvent`) — Dispatched when the committed value changes via user interaction. - **input** (`NordEvent`) — Dispatched as the user types into the search input. - **open** (`NordEvent`) — Dispatched when the listbox is opened. - **close** (`NordEvent`) — Dispatched when the listbox is closed. - **clear** (`ComboboxClearEvent`) — Dispatched when the value is cleared via the clear button or clear(). - **create** (`ComboboxCreateEvent`) — Dispatched when the user chooses the "Create" affordance in a creatable combobox. ### Slots - **start** — Optional slot used to place an icon or prefix at the start of the control. - **end** — Optional slot used to place an icon or suffix at the end of the control. ### Methods - **show** — `show() => void` — Show the listbox programmatically. - **hide** — `hide() => void` — Hide the listbox programmatically. - **focus** — `focus(options?: FocusOptions) => void` — Focus the control's input. ### CSS Custom Properties - `--n-combobox-list-inline-size` — Controls the inline size, or width, of the dropdown list. Defaults to the width of the combobox control. - `--n-combobox-block-size` — Controls the block size, or height, of the control. The medium default is var(--n-space-xl); the s and l sizes scale from it. ### Dependencies - `icon` - `kbd` - `tag`