Skip to content
Nana UI

Forms & Inputs

Combobox

An editable text field paired with a filterable listbox. Type to filter the nana-option children, then pick a value with the keyboard or pointer. The panel flips above the field when it would overflow the viewport.

View .md Download
Apple Banana
npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add combobox --framework web-components
npx @nana-tec/ui add combobox --framework svelte

Lands in src/lib/components/ui/combobox/ as NanaCombobox.svelte, with the same utils/listbox.ts rules module beside it.

Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and each component downloads only the first time a page uses it:

import "@nana-tec/ui-components/autoloader";
import "@nana-tec/ui-components/theme";

The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.

Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:

import "@nana-tec/ui-components/combobox";

Copied in with npx @nana-tec/ui add combobox? Import your project's own @/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.

<nana-combobox label="Fruit" placeholder="Search…" style="min-width:16rem">
<nana-option value="apple">Apple</nana-option>
<nana-option value="banana">Banana</nana-option>
</nana-combobox>
<script lang="ts">
import { NanaCombobox } from '$lib/components/ui/combobox';
const countries = [
{ value: 'ke', label: 'Kenya' },
{ value: 'ug', label: 'Uganda' },
{ value: 'tz', label: 'Tanzania' },
];
let country = $state('');
</script>
<NanaCombobox label="Country" placeholder="Type to filter…" options={countries} bind:value={country} />

value is bindable, and name submits the selected value rather than the label on screen.

Slot an icon into the prefix slot; clearable adds a reset button.

United States Canada Mexico

Properties

PropertyAttributeTypeDefaultDescription
ariaLabelaria-labelstring | nullnullAccessible name when there is no visible label.
clearableclearablebooleanfalseShows a button that clears the value.
disableddisabledbooleanfalseBlocks interaction and leaves the value out of form submission.
errorMessageerror-messagestring''Error under the field while it is invalid, in the error part with role="alert".
helperTexthelper-textstring''Text under the field, in the help part.
inputIdinputId——Id of the inner control. Generated when not set.
invalidinvalidbooleanfalseMarks the field invalid and shows error-message in place of the helper text.
labellabelstring''Visible label for the field.
namenamestring''Name the value is submitted under in a form.
openopenbooleanfalseWhether the panel is open. Set it to open or close the panel yourself.
placeholderplaceholderstring''Hint text shown while the field is empty.
readonlyreadonlybooleanfalseThe value can be read and copied but not changed.
requiredrequiredbooleanfalseThe form will not submit while this has no value.
sizesizeComboboxSize'md'Size preset.
valuevaluestring''Selected option value (the form value)

Methods

MethodDescription
blur(): voidRemove focus from the text field
clear(): voidClear the value and the query, and emit nana-clear
focus(options?: FocusOptions): voidFocus the text field

Events

EventDescription
nana-inputFired while typing (detail.value — the query text)
nana-changeFired when an option is selected (detail.value)
nana-clearFired when the field is cleared
nana-focusFired on focus
nana-blurFired on blur

Slots

SlotDescription
(default)nana-option children
prefixLeading icon inside the field
emptyMessage shown in the panel when no option is left to show (e.g. a nana-empty-state). Defaults to "No results found", or "No options" when there are none to filter.

CSS parts

PartDescription
::part(wrapper)The bordered field container
::part(input)The native <input> element
::part(panel)The floating listbox panel
::part(empty)The empty-message region inside the panel; carries is-custom
::part(field)The field
::part(required-mark)The required mark
::part(prefix)The prefix
::part(controls)The controls
::part(clear-btn)The clear button
::part(caret)The caret
::part(error)The error
::part(help)The helper text
::part(helper)Deprecated: use help
::part(label)The label

CSS custom properties

PropertyDescription
--nana-combobox-max-heightPanel max height before scrolling
--nana-combobox-zStacking order for the suggestion panel
--nana-dropdown-zStacking order for the floating panel, shared by the overlay controls
--nana-input-affix-icon-sizeSize of a slotted prefix or suffix icon
--nana-input-affix-insetDistance from the border to a slotted affix
--nana-input-affix-zoneFixed width reserved for an affix so the text starts in the same place regardless of icon width
--nana-input-bgField background, shared with the other form controls
--nana-input-colorField text colour, shared with the other form controls
--nana-input-heightField height, shared with the other form controls
--nana-input-radiusCorner radius, shared with the other form controls

NanaCombobox

PropTypeDefault
sizeComboboxSize'md'
labelstring
helperTextstring
errorMessagestring
invalidbooleanfalse
optionsComboboxOption[][]
valuebind:string''
namestring
emptySnippet
defaultOpenbooleanfalse
openbind:booleanfalse
onOpenChange(open: boolean) => void
onValueChange(value: string) => void

Also accepts Omit<HTMLInputAttributes, 'class' | 'size' | 'value' | 'name'>.