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.
Preview
Section titled “Preview”<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' },
{ value: 'rw', label: 'Rwanda' },
];
let country = $state('');
</script>
<div class="w-72">
<NanaCombobox
label="Country"
placeholder="Type to filter…"
options={countries}
bind:value={country}
/>
</div> Installation
Section titled “Installation”npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add combobox --framework web-componentsnpx @nana-tec/ui add combobox --framework svelteLands 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.
With a prefix icon
Section titled “With a prefix icon”Slot an icon into the prefix slot; clearable adds a reset button.
<nana-combobox
label="Search country"
placeholder="Type to filter…"
clearable
style="min-width: 16rem"
>
<nana-icon slot="prefix" name="magnifying-glass"></nana-icon>
<nana-option value="us">United States</nana-option>
<nana-option value="ca">Canada</nana-option>
<nana-option value="mx">Mexico</nana-option>
</nana-combobox> Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
ariaLabel | aria-label | string | null | null | Accessible name when there is no visible label. |
clearable | clearable | boolean | false | Shows a button that clears the value. |
disabled | disabled | boolean | false | Blocks interaction and leaves the value out of form submission. |
errorMessage | error-message | string | '' | Error under the field while it is invalid, in the error part with role="alert". |
helperText | helper-text | string | '' | Text under the field, in the help part. |
inputId | inputId | — | — | Id of the inner control. Generated when not set. |
invalid | invalid | boolean | false | Marks the field invalid and shows error-message in place of the helper text. |
label | label | string | '' | Visible label for the field. |
name | name | string | '' | Name the value is submitted under in a form. |
open | open | boolean | false | Whether the panel is open. Set it to open or close the panel yourself. |
placeholder | placeholder | string | '' | Hint text shown while the field is empty. |
readonly | readonly | boolean | false | The value can be read and copied but not changed. |
required | required | boolean | false | The form will not submit while this has no value. |
size | size | ComboboxSize | 'md' | Size preset. |
value | value | string | '' | Selected option value (the form value) |
Methods
| Method | Description |
|---|---|
blur(): void | Remove focus from the text field |
clear(): void | Clear the value and the query, and emit nana-clear |
focus(options?: FocusOptions): void | Focus the text field |
Events
| Event | Description |
|---|---|
nana-input | Fired while typing (detail.value — the query text) |
nana-change | Fired when an option is selected (detail.value) |
nana-clear | Fired when the field is cleared |
nana-focus | Fired on focus |
nana-blur | Fired on blur |
Slots
| Slot | Description |
|---|---|
(default) | nana-option children |
prefix | Leading icon inside the field |
empty | Message 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
| Part | Description |
|---|---|
::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
| Property | Description |
|---|---|
--nana-combobox-max-height | Panel max height before scrolling |
--nana-combobox-z | Stacking order for the suggestion panel |
--nana-dropdown-z | Stacking order for the floating panel, shared by the overlay controls |
--nana-input-affix-icon-size | Size of a slotted prefix or suffix icon |
--nana-input-affix-inset | Distance from the border to a slotted affix |
--nana-input-affix-zone | Fixed width reserved for an affix so the text starts in the same place regardless of icon width |
--nana-input-bg | Field background, shared with the other form controls |
--nana-input-color | Field text colour, shared with the other form controls |
--nana-input-height | Field height, shared with the other form controls |
--nana-input-radius | Corner radius, shared with the other form controls |
NanaCombobox
| Prop | Type | Default |
|---|---|---|
size | ComboboxSize | 'md' |
label | string | |
helperText | string | |
errorMessage | string | |
invalid | boolean | false |
options | ComboboxOption[] | [] |
valuebind: | string | '' |
name | string | |
empty | Snippet | |
defaultOpen | boolean | false |
openbind: | boolean | false |
onOpenChange | (open: boolean) => void | |
onValueChange | (value: string) => void |
Also accepts Omit<HTMLInputAttributes, 'class' | 'size' | 'value' | 'name'>.