Autocomplete New Alpha Light DOM & Tailwind
A free-text input with suggestions, where the text the user types is itself the value and the options are completion aids.
Usage
Autocomplete is a free-text input with suggestions: the text the user types is the committed value (a string), and the options are completion aids. Picking a suggestion fills the input with that option's label and commits it. Reach for it when the answer is open-ended text but you can offer helpful completions — a city, a tag, a username.
When the value must be one of a fixed set of options, use Combobox instead.
Autocomplete renders its built-in label, hint and error on its own. Wrapped in a Field, the Field takes over with a Field Label, Field Description and Field Error, and the built-in versions step aside automatically.
import "@nordhealth/components/lib/Autocomplete"
import "@nordhealth/components/lib/Field"
import "@nordhealth/components/lib/FieldLabel"
import "@nordhealth/components/lib/FieldDescription"
Set the suggestions with the .options JavaScript property, where each option is an object with a value and a label:
Standalone or inside a Field
Use the control on its own with its built-in label, hint and error, or wrap it in a Field — the Field then provides the labelling. Both render the same control:
Examples
Inline completion
Add inline for ghost-text completion. While an option is highlighted with the arrow keys, the input shows the typed query followed by the remainder of the highlighted option's label, with that remainder text-selected so continued typing overwrites it. Accepting (Enter, → / End at the end of the text, or a click) commits the full label.
Async search
Add external-filtering to take over filtering yourself — listen for input, fetch matches, and assign them to .options. Set loading to show a spinner while the request is in flight. Because the typed text is the value, the input keeps what the user typed while results load.
Grouped options
Give each option a group to cluster related options together under a heading.
Clearable
Add clearable to show a clear button that resets the value to an empty string while there is text.
Auto highlight
Add auto-highlight to highlight the first matching option as the user types, so it can be accepted by pressing Enter.
Invalid
Mark the surrounding Field as invalid to show the error state.
Virtualized
Add virtualized for very large suggestion lists. The autocomplete renders only the options in view (windowing), so thousands of suggestions stay fast.
Disabled items
Mark individual options with disabled to keep them visible but unselectable. They are skipped during keyboard navigation.
Open on focus
By default the suggestions open when the autocomplete receives focus. Set open-on-focus to false to require a keystroke or click before they appear.
Input group
Autocomplete composes inside an Input Group so you can pair it with buttons or other controls as a single unit.
RTL
Autocomplete follows the document or container direction. Toggle the direction to see the layout mirror.
Accessibility
- Autocomplete has no built-in label. Wrap it in a Field with a Field Label so it has an accessible name, and use Field Error for validation messages.
- The inner input is a
role="combobox"whosearia-autocompletereflects the active behaviour:list(suggestions, no inline),both(suggestions + inline ghost),inline(external filtering + inline ghost) ornone(external filtering, no inline). - The highlighted option is tracked with
aria-activedescendantso screen reader users hear the current completion while typing. Because the typed text is the value, options are completion aids rather than a selection — they carry noaria-selectedand never show a selected-check icon. - The full keyboard pattern is supported: type to filter, move through suggestions with the arrow keys, accept the highlighted option with Enter (or, in
inlinemode, → / End at the end of the text), and dismiss the list with Escape. - When
clearableis set, the clear button has an accessible label so its purpose is announced.
API reference
Autocomplete
Autocomplete is a free-text input with suggestions: the text the user types
is itself the committed value (a string), and the options are completion
aids. Picking a suggestion fills the input with the option's label and commits
that label. Use it when the answer is open-ended text but you can offer
helpful completions (a city, a tag, a username); reach for
Combobox instead when the value must be one of a
fixed set of options.
Autocomplete 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.
Base UI parity: Autocomplete is the Combobox primitive with
selectionMode="none" + fillInputOnItemPress.
<nord-autocomplete></nord-autocomplete>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
value | value | The value of the autocomplete. This is the free text the user has typed (or
the label of a picked suggestion) — always a single string. | string | '' |
inline | inline | Enables inline ghost-text completion. While an option is highlighted with the keyboard, the input shows the typed query followed by the remainder of the highlighted option's label, with that remainder text-selected so continued typing overwrites it. Accepting (Enter, ArrowRight/End at the end of the text, or an option click) commits the full label. | boolean | false |
clearable | clearable | Shows a clear (✕) button while there is text. Pressing it resets the value
to '', then fires clear and change. | boolean | false |
openOnFocus | open-on-focus | Whether focusing the input opens the suggestion list. Defaults to false
for autocomplete — matching Base UI's openOnInputClick={false}, the list
appears as the user types rather than on focus. Set to true to also open
on focus. | boolean | false |
size | size | The size of the component. | 's' | 'm' | 'l' | 'm' |
autocomplete | autocomplete | Specifies the data type of the field, so that the browser may attempt to fill out the field automatically on behalf of the user. | AutocompleteAttribute | 'off' |
required | required | 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. | boolean | false |
disabled | disabled | Makes the component disabled. This prevents users from being able to interact with the component, and conveys its inactive state to assistive technologies. | boolean | false |
name | name | The name of the form component. | string | undefined | — |
form | form | Gets the form, if any, associated with the form element. The setter accepts a string, which is the id of the form. | HTMLFormElement | null | — |
open | open | Controls whether the component is open or not. | boolean | false |
align | align | 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. | 'start' | 'end' | 'start' |
position | position | 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. | 'block-end' | 'block-start' | 'inline-start' | 'inline-end' | 'auto' | 'block-end' |
sideOffset | side-offset | 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. | number | 8 |
alignOffset | align-offset | 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. | number | 0 |
placeholder | placeholder | Placeholder text to display within the input. | string | undefined | — |
externalFiltering | external-filtering | 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. | boolean | false |
loading | loading | Shows a spinner in the control and listbox while asynchronous results are
loading. Pair with external-filtering for async search. | boolean | false |
autoHighlight | auto-highlight | Highlights the first option after filtering so pressing Enter selects it. | boolean | false |
invalid | invalid | Marks the control as invalid, applying error styling and setting
aria-invalid on the input. | boolean | false |
readonly | readonly | 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. | boolean | false |
noResultsText | no-results-text | Message shown when no options match the query. Defaults to "No items found.". | string | undefined | — |
virtualized | virtualized | 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. | boolean | false |
Field properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
label | label | Label for the control. Ignored when the control is wrapped in a
<nord-field>, which provides the label via <nord-field-label>. | string | '' |
hint | hint | Optional hint text shown with the control. Ignored inside a <nord-field>,
which provides it via <nord-field-description>. | string | undefined | — |
hintBelow | hint-below | Renders the hint below the control and any error instead of below the label. | boolean | false |
hideLabel | hide-label | Visually hide the label, but still expose it to assistive technologies. | boolean | false |
error | error | Optional error shown with the control. Ignored inside a <nord-field>,
which provides it via <nord-field-error>. | string | undefined | — |
hideRequired | hide-required | Visually hide the required indicator, but still expose the required state to assistive technologies. | boolean | false |
Slots
| Slot name | Description |
|---|---|
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
| Method name | Parameters | Description |
|---|---|---|
show() => void | N/A | Show the listbox programmatically. |
hide() => void | N/A | Hide the listbox programmatically. |
focus(options?: FocusOptions) => void | options: FocusOptions | Focus the control's input. |
| Event | Detail Type | Description |
|---|---|---|
change | NordEvent | Dispatched when the committed value changes via user interaction. |
input | NordEvent | Dispatched as the user types into the 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(). |
CSS Properties
CSS Custom Properties provide more fine grain control over component presentation. We advise utilizing existing properties on the component before using these.
| Property | Description | Default |
|---|---|---|
--n-combobox-list-inline-size | Controls the inline size, or width, of the dropdown list. Defaults to the width of the 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. | — |
State attributes
These data-* attributes are set by the component to reflect its current state. Use them as styling hooks — they are read-only and should not be set manually.
| Attribute | Description |
|---|---|
data-invalid | Present while the control is invalid (mirrors the invalid property). Style hook for the whole control. |
data-focused | Present while the control has focus. Style hook for focus-within treatments. |
Dependencies
This component is internally dependent on the following components:
Design guidelinesFor designers
Usage
Autocomplete is a control only — it has no built-in label, hint or error. Pair it with a Field to give it a label, helper text and an error message, exactly like a native input. Connect the Field Label to the autocomplete with the for attribute so it gets an accessible name and click-to-focus.
Import the autocomplete and the Field parts you need — each import registers its custom element:
import '@nordhealth/components/lib/Autocomplete'
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 autocomplete:
<nord-field>
<nord-field-label for="tag">Search tags</nord-field-label>
<nord-autocomplete id="tag" placeholder="e.g. feature"></nord-autocomplete>
<nord-field-description>The text you type is the value; suggestions help you complete it.</nord-field-description>
<!-- show a Field Error and mark the Field invalid instead, when validation fails -->
</nord-field>
Provide the suggestions with the options property — pairing it with a Field only handles labelling and layout, it doesn't change how you populate the list:
document.querySelector('nord-autocomplete').options = [
{ value: 'feature', label: 'feature' },
{ value: 'fix', label: 'fix' },
]
Autocomplete renders in the light DOM, so you can style it directly with your own CSS or Tailwind utilities, and set its width on the autocomplete (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.
Free text is the value
The text the user types is the committed value (a single string). Suggestions are completion aids: picking one fills the input with that option's label and commits that label. Nothing is discarded when the listbox closes — the typed text stays as the value and the filter query.
Add inline for ghost-text completion: while an option is highlighted with the arrow keys, the input previews the highlighted option's remaining label as selected text that the user can accept (Enter, → / End at the end of the text, or a click) or overwrite by continuing to type.
The value is distinct from the inherited native HTML-autofill autocomplete property; the inner input always hard-codes autocomplete="off" so browser autofill never fights the suggestion list.
Autocomplete vs Combobox
Both let users type to filter a list, but they differ in what the value becomes:
- Autocomplete — the raw typed text is committed directly as
value. Suggestions optionally complete it; the value can be anything the user types. - Combobox — the
valuemust be one of the options'values. The input is a search/filter field whose text is discarded on commit unless the user picks an option.
Do
- Use when the answer is open-ended text but you can offer helpful completions, such as a city, a tag or a username.
- Pair it with a Field and a Field Label connected with
for, so it has an accessible name, helper text and an error message. - Use
external-filteringand updateoptionsfrom theinputevent when the suggestions come from a server. - Group related suggestions with the
groupproperty to help users scan long lists.
Don’t
- Don’t use when the value must be one of a fixed set of options, see Combobox instead.
- Don’t add a Field Label without a
forpointing at the autocomplete’sid, or the control will have no accessible name. - Don’t use for plain free-form text entry with no useful suggestions, see Input instead.
- Don’t use to trigger actions or commands, see Command Menu instead.