Combobox#
Component <neo-combobox> is a search-driven sibling of Select. Trigger, popover, <neo-option> / <neo-optgroup> children, and the lazy / async lifecycle are identical; the panel adds a pinned, auto-focusing search input that filters the listbox client-side. ArrowDown / ArrowUp bridge between input and listbox at either end.
Default
Disabled control
Grouped options
Multiple selection
Rich options
Custom trigger face
Multi-select chips
Open above
No cities match "".
The selected state's markup and its scoped CSS. The CSS is wrapped in <style>@scope { ... }</style> and applies to the preview only. Edits change the preview above, applied live while Sync is on, or when you click Patch or Replace. Patch morphs the preview; Replace swaps it outright.
Signals
Datastar signals declared in the selected state's markup. Change a value to drive the preview, applied live while Sync is on, or when you click Patch.
Reference#
| Name | Type | Default | Description |
|---|---|---|---|
value | string | none | Selected value(s); comma-separated when multiple is set. In multiple mode an option value must not contain a comma; the separator is unescaped. |
name | string | none | Form field name. The control is form-associated: with a name set it submits its value in a native <form>, resets with the form, and is barred from submission while disabled. With multiple it submits one entry per selected value under the same name, like <select multiple>. |
size | "sm" | "lg" | none | Control-size step: sm compact, lg large. Omit for the default size. |
disabled | boolean | false | Makes the control non-interactive: the trigger drops out of the tab order and ignores clicks and keys, and an open panel closes. |
placeholder | string | none | Trigger text when nothing is selected. |
list | string | none | References a shared <neo-datalist> by its id (like native <input list>) to source the options. Inline <neo-option> children (or an inline datalist) take precedence. |
search-placeholder | string | "Search…" | Hint shown in the search input. |
multiple | boolean | false | Allow multi-selection; value becomes a comma-separated list. |
clearable | boolean | false | Backspace / Delete on the focused (closed) trigger clears the selection back to the empty state. |
caret | string | "chevrons-up-down" | Name of the trigger's caret icon. Resolved through <neo-icon>, so it follows the active icon theme. Set caret="" (empty) to hide the caret entirely. |
async | boolean | false | On every open, clear the listbox, re-show the [data-neo-async-placeholder] slot, and fire neo-combobox-load so a wired loader re-fetches. Without async, a combobox with a [data-neo-async-placeholder] child fires neo-combobox-load only on the first open (options empty) and caches across opens; neo-popover-open is independent; it always fires when the panel opens. |
live-search | boolean | false | Reload options on every keystroke. |
search-debounce | number | 0 | Milliseconds to coalesce keystrokes before running the local filter / live-search loading reset and dispatching neo-combobox-search. 0 dispatches on every keystroke. |
placement | string | "bottom-start" | Anchor placement of the panel. The listbox positions the panel with the same helper as <neo-popover>; see its placement values. |
screen-offset | string | none | Viewport edge margin and the panel's scrollable max size. |
follow-scroll | "always" | "until-trigger-invisible" | unset | When absent, close on outside scroll. Set to always to stay anchored during scroll. Set to until-trigger-invisible to close once the trigger leaves the viewport. |
clamp-placement | boolean | false | Default is strict placement (panel anchored at the exact point, content scrolls); set this to opt into re-anchoring the panel position so it stays inside the viewport when content would overflow. |
min-fit-height | CSS length | "content" | "content" | Minimum vertical slot the strict placement requires; below the threshold the panel auto-flips to the opposite primary axis when the other side has more room. content resolves from the panel's scroll height on each positioning pass. |
min-fit-width | CSS length | "content" | "content" | Same as min-fit-height but for the horizontal axis. content resolves from the panel's scroll width. Use 0 to disable the horizontal auto-flip. |
min-open-height | CSS length | 2rem | Minimum usable vertical slot required to remain open after placement and auto-flip. If the bounded slot is smaller, the listbox closes instead of rendering a cramped panel. Use 0 to disable. |
min-open-width | CSS length | 2rem | Same as min-open-height but for horizontal space. Use 0 to disable. |
popover-fit-content | boolean | false | The listbox tracks the trigger width by default; set this to size the panel to the option rows instead. Capped by --neo-popover-max-width and the viewport. |
hover | boolean | false | Open the panel on trigger hover without moving focus; close after the pointer leaves both trigger and panel. Mouse only; touch falls back to click. While set, clicking the trigger always shows the panel instantly and never toggles it shut, so touch and keyboard users keep a way in. |
hover-open-delay | integer (ms) | 100 | Milliseconds the pointer must rest on the trigger before hover opens the panel. Filters incidental cursor crossings. Does not apply to click. |
hover-close-delay | integer (ms) | 200 | Milliseconds to wait after the pointer leaves both trigger and panel before hover closes the panel. Long enough to bridge the gap between them. |
| Name | Description |
|---|---|
| default | <neo-option> and <neo-optgroup> children. Alternatively, set list to source them from a shared <neo-datalist>. |
[data-neo-async-placeholder] | Shown in the listbox whenever there are no options. The kit clones the slot under the search field; when the slot is absent, a default <neo-spinner> stands in. |
[slot=trigger] | Owns the trigger face. Leave it absent and the kit fills it client-side by cloning the selected option's body (so its CSS styles it and the trigger grows to fit); provide one (e.g. patched from a server) and the kit yields, rendering exactly your content. |
[data-neo-option-trigger] | Optional per-<neo-option> child: a compact trigger face distinct from the option's rich list row. Hidden in the list; cloned into the trigger when that option is selected. Falls back to the option's label (plain text), then its full body. Shared with <neo-select>. |
[data-neo-combobox-empty] | The empty-state trigger face, cloned into the trigger when nothing is selected. Hidden in the list. |
[data-neo-empty-results] | Overrides the default No results hint when the listbox ends up empty after filtering or after an external load returned no options. Any [data-neo-empty-query] descendants get their textContent set to the current search input each time the slot is mounted, so authors can render messages like No results for "<span data-neo-empty-query></span>". A response can also ship one inline as an option-list child. |
| Name | Detail | Bubbles | Description |
|---|---|---|---|
neo-combobox-change | { value, label } or { values, labels } | yes | Fires after the selection changes. Multiple-mode payload uses array fields. |
neo-combobox-search | { query: string } | yes | Fires on every search-input change; detail.query carries the current text. For server-driven live search, copy it into a signal in the handler (the element binds no framework attribute itself). |
neo-combobox-load | none | yes | Fires when options need fetching: every open with async, or a lazy combobox's first open. Wire a loader to it (e.g. a Datastar @post). Call el.reload() to re-fire it. Distinct from neo-popover-open, which always fires on open. |
| Name | Description |
|---|---|
::part(label) | Trigger label showing the current selection. |
::part(caret) | Trigger caret icon. |
| Name | Default | Description |
|---|---|---|
--neo-combobox-min-width | var(--neo-select-min-width, 12rem) | Minimum trigger width. |
--neo-combobox-search-padding | calc(var(--page-spacing, 0.25rem) * 2) calc(var(--page-spacing, 0.25rem) * 2.5) | Padding around the search field. |
--neo-combobox-search-divider | color-mix(in srgb, var(--page-fg) 10%, transparent) | Divider color between the search field and the options list. |
--neo-combobox-search-divider-width | 1px | Divider width between the search field and the options list. |
Examples#
Disabled control#
Set disabled on the host to make the whole control non-interactive: the trigger leaves the tab order, ignores clicks and keys, and renders faded. An open panel closes. Distinct from disabling individual options.
Native form submission#
The combobox is form-associated. Give it a name and it submits in a plain <form>, no framework binding. In multiple mode it posts one entry per selected value under the same name, like <select multiple>. Submit to see the posted values.
Grouped options#
Group related options under labeled headers by wrapping them in <neo-optgroup label="…">.
- The group header is not focusable; arrow keys step across groups.
- Each option's
labelkeeps the trigger and search clean text, even when the option body is rich markup. - Searching hides a whole group once all its options drop out. Type tokyo to watch the others collapse.
Multiple selection#
Pick several options at once with multiple.
- Clicking an option toggles it and keeps the popover open; single-select replaces and closes.
valueis a comma-separated list andneo-combobox-changecarries{values, labels}.- A
[data-neo-empty-results]child replaces the no-match row;[data-neo-empty-query]inside it echoes the typed text. Type xyz to see it.
No languages match "@neo.EmptyQuery()".
Rich options#
Options carry rich multi-line bodies (avatar, name, title) that also render in the trigger.
- The selected option's body is cloned into the trigger, which grows to fit it.
- Search matches each option's
labelor text. [data-neo-combobox-empty]is the face shown when nothing is selected;clearablelets Backspace or Delete on the trigger clear the selection.- A server can swap the trigger face by patching a
slot="trigger"child.
Custom trigger face#
Show a compact face on the trigger, separate from the full row in the list.
- A
[data-neo-option-trigger]child is cloned onto the trigger; the rest of the option stays the list row. [data-neo-combobox-empty]is the empty face. Press Backspace on the trigger to clear and show it.
Unassigned
Diego Vega
CFO
Jan O'Sullivan
Lead Designer
Evelyn Kone
Data Analyst
Samira Khalil
Head of Engineering
Alice Larsson
Product Manager
Camila Duarte
DevOps Engineer
Theo Becker
UX Researcher
Mateusz Wiśniewski
Fullstack Engineer
Multi-select chips#
multiple with per-option faces: each pick becomes a chip on the trigger.
- A chip uses the option's
[data-neo-option-trigger]face, or falls back to its text. - Chips wrap and the trigger grows. Drag the stage narrower to watch them reflow.
Diego Vega
CFO
Jan O'Sullivan
Lead Designer
Evelyn Kone
Data Analyst
Samira Khalil
Head of Engineering
Alice Larsson
Product Manager
Camila Duarte
DevOps Engineer
Theo Becker
UX Researcher
Mateusz Wiśniewski
Fullstack Engineer
Open above#
Open the panel above the trigger with placement="top-start".
- The search input stays pinned next to the trigger (bottom of the panel), even as placement flips.
- ArrowUp moves to the nearest option (last in the DOM); ArrowDown wraps to the first.
Examples: Datastar#
Morphing during interaction#
A Datastar fat-morph can replace the option list while the user is interacting; the combobox reconciles in place.
- Options can appear, disappear, or flip to
disabledwith the popover open. - The element stays mounted, the popover stays open, and the selection survives. Autoplay cycles the states below to simulate the morphs.
Default
Add more options
Disable some options
No cities match "".
The selected state's markup and its scoped CSS. The CSS is wrapped in <style>@scope { ... }</style> and applies to the preview only. Edits change the preview above, applied live while Sync is on, or when you click Patch or Replace. Patch morphs the preview; Replace swaps it outright.
Signals
Datastar signals declared in the selected state's markup. Change a value to drive the preview, applied live while Sync is on, or when you click Patch.
Async load#
Fetch options from the server on every open with async.
- Each open fires
neo-combobox-load; wiredata-on:neo-combobox-loadto post. - The server morphs an options fragment into
#<host-id>-options. [data-neo-async-placeholder]fills the listbox until options arrive; the search field stays usable.
Loading states only show with simulated delay. Raise network latency or handler delay in the Settings panel.
Lazy load#
Fetch options once, on first open, then reuse them.
- Add a
[data-neo-async-placeholder]withoutasync: the first open firesneo-combobox-load. - Loaded options are cached; later opens reuse them with no refetch.
Loading states only show with simulated delay. Raise network latency or handler delay in the Settings panel.
Live search (server-driven)#
Let the server filter on every keystroke instead of matching locally, with live-search.
- Each keystroke re-shows the placeholder and refetches; wire
data-on:neo-combobox-searchto re-post. - The event's
event.detail.queryholds the typed text; copy it into a signal the server reads. - The server returns the matching options, or a
[data-neo-empty-results]child when nothing matches.
Async load with failure swap#
Async load that shows a failure state and a retry button when the request keeps failing.
- On a failed request Datastar retries per its retry config; after retries are exhausted, a failure template replaces the
[data-neo-async-placeholder]. - A
[data-neo-popover-async-retry]button re-runs the load without closing the panel. - The placeholder stays the source, so reopening shows the loading view again.
Loading states only show with simulated delay. Raise network latency or handler delay in the Settings panel.