Skip to content
WebJs
Menu

Autocomplete input with a list of suggestions.

No items found.
Next.js
SvelteKit
Nuxt.js
Remix
Astro
import { html } from '@webjsdev/core';

const frameworks = ['Next.js', 'SvelteKit', 'Nuxt.js', 'Remix', 'Astro'];

export default function ComboboxBasic() {
  return html`
    <ui-combobox>
      <ui-combobox-input placeholder="Select a framework" aria-label="Framework"></ui-combobox-input>
      <ui-combobox-content>
        <ui-combobox-empty>No items found.</ui-combobox-empty>
        <ui-combobox-list>
          ${frameworks.map((item) => html`<ui-combobox-item value=${item}>${item}</ui-combobox-item>`)}
        </ui-combobox-list>
      </ui-combobox-content>
    </ui-combobox>
  `;
}
View Code

Installation

pnpm dlx @webjsdev/ui add combobox

Usage

import '#components/ui/combobox.ts';
const frameworks = ['Next.js', 'SvelteKit', 'Nuxt.js', 'Remix', 'Astro'];

export function exampleCombobox() {
  return html`
    <ui-combobox name="framework">
      <ui-combobox-input placeholder="Select a framework" aria-label="Framework"></ui-combobox-input>
      <ui-combobox-content>
        <ui-combobox-empty>No items found.</ui-combobox-empty>
        <ui-combobox-list>
          ${frameworks.map((item) => html`<ui-combobox-item value=${item}>${item}</ui-combobox-item>`)}
        </ui-combobox-list>
      </ui-combobox-content>
    </ui-combobox>
  `;
}

Composition

Simple

A single-line input and a flat list (see Basic).

ui-combobox
├── ui-combobox-input
└── ui-combobox-content
    ├── ui-combobox-empty
    └── ui-combobox-list
        ├── ui-combobox-item
        └── ui-combobox-item

With chips

Multi-select with multiple, chips, and a chips input (see Multiple). The chips are drawn from the chosen values, so the markup holds only the chips input.

ui-combobox multiple
├── ui-combobox-chips
│   └── ui-combobox-chips-input
└── ui-combobox-content
    ├── ui-combobox-empty
    └── ui-combobox-list
        ├── ui-combobox-item
        └── ui-combobox-item

With groups and collection

Items nested in each <ui-combobox-group>, with a separator between groups (see Groups). The items go straight into the group, after its label.

ui-combobox
├── ui-combobox-input
└── ui-combobox-content
    ├── ui-combobox-empty
    └── ui-combobox-list
        ├── ui-combobox-group
        │   ├── ui-combobox-label
        │   ├── ui-combobox-item
        │   ├── ui-combobox-item
        │   └── ui-combobox-separator
        └── ui-combobox-group
            ├── ui-combobox-label
            ├── ui-combobox-item
            └── ui-combobox-item

Custom Items

When your items are objects, render one <ui-combobox-item> per object, with the object's id as its value and its label as its text. The list filters on the text, and the form submits the value.

type Framework = {
  label: string;
  value: string;
};

const frameworks: Framework[] = [
  { label: 'Next.js', value: 'next' },
  { label: 'SvelteKit', value: 'sveltekit' },
  { label: 'Nuxt', value: 'nuxt' },
];

export function exampleComboboxCustomItems() {
  return html`
    <ui-combobox name="framework">
      <ui-combobox-input placeholder="Select a framework" aria-label="Framework"></ui-combobox-input>
      <ui-combobox-content>
        <ui-combobox-empty>No items found.</ui-combobox-empty>
        <ui-combobox-list>
          ${frameworks.map((framework) => html`
            <ui-combobox-item value=${framework.value}>${framework.label}</ui-combobox-item>
          `)}
        </ui-combobox-list>
      </ui-combobox-content>
    </ui-combobox>
  `;
}

Multiple Selection

Use multiple with chips for multi-select behavior. value holds the initial choice as a comma separated list, every choice is submitted as its own name entry, and ui-value-change reports the array as it changes.

const frameworks = ['Next.js', 'SvelteKit', 'Nuxt.js', 'Remix', 'Astro'];

export function exampleComboboxMultiple() {
  return html`
    <ui-combobox name="frameworks" multiple @ui-value-change=${(e: CustomEvent<{ value: string[] }>) => console.log(e.detail.value)}>
      <ui-combobox-chips>
        <ui-combobox-chips-input placeholder="Add framework" aria-label="Frameworks"></ui-combobox-chips-input>
      </ui-combobox-chips>
      <ui-combobox-content>
        <ui-combobox-empty>No items found.</ui-combobox-empty>
        <ui-combobox-list>
          ${frameworks.map((item) => html`<ui-combobox-item value=${item}>${item}</ui-combobox-item>`)}
        </ui-combobox-list>
      </ui-combobox-content>
    </ui-combobox>
  `;
}

Basic

A simple combobox with a list of frameworks.

No items found.
Next.js
SvelteKit
Nuxt.js
Remix
Astro
import { html } from '@webjsdev/core';

const frameworks = ['Next.js', 'SvelteKit', 'Nuxt.js', 'Remix', 'Astro'];

export default function ComboboxBasic() {
  return html`
    <ui-combobox>
      <ui-combobox-input placeholder="Select a framework" aria-label="Framework"></ui-combobox-input>
      <ui-combobox-content>
        <ui-combobox-empty>No items found.</ui-combobox-empty>
        <ui-combobox-list>
          ${frameworks.map((item) => html`<ui-combobox-item value=${item}>${item}</ui-combobox-item>`)}
        </ui-combobox-list>
      </ui-combobox-content>
    </ui-combobox>
  `;
}
View Code

Multiple

A combobox with multiple selection using multiple and <ui-combobox-chips>.

No items found.
Next.js
SvelteKit
Nuxt.js
Remix
Astro
import { html } from '@webjsdev/core';

const frameworks = ['Next.js', 'SvelteKit', 'Nuxt.js', 'Remix', 'Astro'];

// The chips are drawn from the chosen values, so the markup holds only the
// chips input. `value` is the initial choice, comma separated.
export default function ComboboxMultiple() {
  return html`
    <ui-combobox multiple value=${frameworks[0]} class="w-full max-w-xs">
      <ui-combobox-chips>
        <ui-combobox-chips-input aria-label="Frameworks"></ui-combobox-chips-input>
      </ui-combobox-chips>
      <ui-combobox-content>
        <ui-combobox-empty>No items found.</ui-combobox-empty>
        <ui-combobox-list>
          ${frameworks.map((item) => html`<ui-combobox-item value=${item}>${item}</ui-combobox-item>`)}
        </ui-combobox-list>
      </ui-combobox-content>
    </ui-combobox>
  `;
}
View Code

Clear Button

Use the show-clear attribute to show a clear button.

No items found.
Next.js
SvelteKit
Nuxt.js
Remix
Astro
import { html } from '@webjsdev/core';

const frameworks = ['Next.js', 'SvelteKit', 'Nuxt.js', 'Remix', 'Astro'];

export default function ComboboxWithClear() {
  return html`
    <ui-combobox value=${frameworks[0]}>
      <ui-combobox-input placeholder="Select a framework" aria-label="Framework" show-clear></ui-combobox-input>
      <ui-combobox-content>
        <ui-combobox-empty>No items found.</ui-combobox-empty>
        <ui-combobox-list>
          ${frameworks.map((item) => html`<ui-combobox-item value=${item}>${item}</ui-combobox-item>`)}
        </ui-combobox-list>
      </ui-combobox-content>
    </ui-combobox>
  `;
}
View Code

Groups

Use <ui-combobox-group> and <ui-combobox-separator> to group items.

No timezones found.
Americas
(GMT-5) New York
(GMT-8) Los Angeles
(GMT-6) Chicago
(GMT-5) Toronto
(GMT-8) Vancouver
(GMT-3) São Paulo
Europe
(GMT+0) London
(GMT+1) Paris
(GMT+1) Berlin
(GMT+1) Rome
(GMT+1) Madrid
(GMT+1) Amsterdam
Asia/Pacific
(GMT+9) Tokyo
(GMT+8) Shanghai
(GMT+8) Singapore
(GMT+4) Dubai
(GMT+11) Sydney
(GMT+9) Seoul
import { html } from '@webjsdev/core';

const timezones = [
  {
    value: 'Americas',
    items: [
      '(GMT-5) New York',
      '(GMT-8) Los Angeles',
      '(GMT-6) Chicago',
      '(GMT-5) Toronto',
      '(GMT-8) Vancouver',
      '(GMT-3) São Paulo',
    ],
  },
  {
    value: 'Europe',
    items: [
      '(GMT+0) London',
      '(GMT+1) Paris',
      '(GMT+1) Berlin',
      '(GMT+1) Rome',
      '(GMT+1) Madrid',
      '(GMT+1) Amsterdam',
    ],
  },
  {
    value: 'Asia/Pacific',
    items: [
      '(GMT+9) Tokyo',
      '(GMT+8) Shanghai',
      '(GMT+8) Singapore',
      '(GMT+4) Dubai',
      '(GMT+11) Sydney',
      '(GMT+9) Seoul',
    ],
  },
];

export default function ComboboxWithGroupsAndSeparator() {
  return html`
    <ui-combobox>
      <ui-combobox-input placeholder="Select a timezone" aria-label="Timezone"></ui-combobox-input>
      <ui-combobox-content>
        <ui-combobox-empty>No timezones found.</ui-combobox-empty>
        <ui-combobox-list>
          ${timezones.map((group, index) => html`
            <ui-combobox-group>
              <ui-combobox-label>${group.value}</ui-combobox-label>
              ${group.items.map((item) => html`<ui-combobox-item value=${item}>${item}</ui-combobox-item>`)}
              ${index < timezones.length - 1 ? html`<ui-combobox-separator></ui-combobox-separator>` : ''}
            </ui-combobox-group>
          `)}
        </ui-combobox-list>
      </ui-combobox-content>
    </ui-combobox>
  `;
}
View Code

Custom Items

You can render custom markup inside <ui-combobox-item>. The item's whole text is what the list filters on.

No countries found.
Argentina

South America (ar)

Australia

Oceania (au)

Brazil

South America (br)

Canada

North America (ca)

China

Asia (cn)

Colombia

South America (co)

Egypt

Africa (eg)

France

Europe (fr)

Germany

Europe (de)

Italy

Europe (it)

Japan

Asia (jp)

Kenya

Africa (ke)

Mexico

North America (mx)

New Zealand

Oceania (nz)

Nigeria

Africa (ng)

South Africa

Africa (za)

South Korea

Asia (kr)

United Kingdom

Europe (gb)

United States

North America (us)

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  itemClass, itemContentClass, itemTitleClass, itemDescriptionClass,
} from '#components/ui/item.ts';

const countries = [
  { code: '', value: '', continent: '', label: 'Select country' },
  { code: 'ar', value: 'argentina', label: 'Argentina', continent: 'South America' },
  { code: 'au', value: 'australia', label: 'Australia', continent: 'Oceania' },
  { code: 'br', value: 'brazil', label: 'Brazil', continent: 'South America' },
  { code: 'ca', value: 'canada', label: 'Canada', continent: 'North America' },
  { code: 'cn', value: 'china', label: 'China', continent: 'Asia' },
  { code: 'co', value: 'colombia', label: 'Colombia', continent: 'South America' },
  { code: 'eg', value: 'egypt', label: 'Egypt', continent: 'Africa' },
  { code: 'fr', value: 'france', label: 'France', continent: 'Europe' },
  { code: 'de', value: 'germany', label: 'Germany', continent: 'Europe' },
  { code: 'it', value: 'italy', label: 'Italy', continent: 'Europe' },
  { code: 'jp', value: 'japan', label: 'Japan', continent: 'Asia' },
  { code: 'ke', value: 'kenya', label: 'Kenya', continent: 'Africa' },
  { code: 'mx', value: 'mexico', label: 'Mexico', continent: 'North America' },
  { code: 'nz', value: 'new-zealand', label: 'New Zealand', continent: 'Oceania' },
  { code: 'ng', value: 'nigeria', label: 'Nigeria', continent: 'Africa' },
  { code: 'za', value: 'south-africa', label: 'South Africa', continent: 'Africa' },
  { code: 'kr', value: 'south-korea', label: 'South Korea', continent: 'Asia' },
  { code: 'gb', value: 'united-kingdom', label: 'United Kingdom', continent: 'Europe' },
  { code: 'us', value: 'united-states', label: 'United States', continent: 'North America' },
];

// An item's value is its `value` attribute and its label is its text, so an
// object list maps to items with the id as the value.
export default function ComboboxWithCustomItems() {
  return html`
    <ui-combobox>
      <ui-combobox-input placeholder="Search countries..." aria-label="Country"></ui-combobox-input>
      <ui-combobox-content>
        <ui-combobox-empty>No countries found.</ui-combobox-empty>
        <ui-combobox-list>
          ${countries.filter((country) => country.code !== '').map((country) => html`
            <ui-combobox-item value=${country.value}>
              <div data-slot="item" data-variant="default" data-size="xs" class=${cn(itemClass({ size: 'xs' }), 'p-0')}>
                <div data-slot="item-content" class=${itemContentClass()}>
                  <div data-slot="item-title" class=${cn(itemTitleClass(), 'whitespace-nowrap')}>${country.label}</div>
                  <p data-slot="item-description" class=${itemDescriptionClass()}>${country.continent} (${country.code})</p>
                </div>
              </div>
            </ui-combobox-item>
          `)}
        </ui-combobox-list>
      </ui-combobox-content>
    </ui-combobox>
  `;
}
View Code

Invalid

The input part renders its own input and does not pass aria-invalid on to it yet, so mark the invalid state on the field around the combobox, with data-invalid and an error message.

No items found.
Next.js
SvelteKit
Nuxt.js
Remix
Astro
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { fieldClass, fieldLabelClass, fieldErrorClass } from '#components/ui/field.ts';

const frameworks = ['Next.js', 'SvelteKit', 'Nuxt.js', 'Remix', 'Astro'];

// The input part renders its own input and does not pass aria-invalid on to
// it yet, so the invalid state is carried by the field around it:
// data-invalid on the field, and the error below the control.
export default function ComboboxInvalid() {
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" data-invalid="true" class=${cn(fieldClass(), 'w-full max-w-xs')}>
      <label data-slot="field-label" for="combobox-invalid" class=${fieldLabelClass()}>Framework</label>
      <ui-combobox>
        <ui-combobox-input input-id="combobox-invalid" placeholder="Select a framework"></ui-combobox-input>
        <ui-combobox-content>
          <ui-combobox-empty>No items found.</ui-combobox-empty>
          <ui-combobox-list>
            ${frameworks.map((item) => html`<ui-combobox-item value=${item}>${item}</ui-combobox-item>`)}
          </ui-combobox-list>
        </ui-combobox-content>
      </ui-combobox>
      <div role="alert" data-slot="field-error" class=${fieldErrorClass()}>Please select a framework.</div>
    </div>
  `;
}
View Code

Disabled

Use the disabled attribute on <ui-combobox> to disable the combobox.

No items found.
Next.js
SvelteKit
Nuxt.js
Remix
Astro
import { html } from '@webjsdev/core';

const frameworks = ['Next.js', 'SvelteKit', 'Nuxt.js', 'Remix', 'Astro'];

export default function ComboboxDisabled() {
  return html`
    <ui-combobox disabled>
      <ui-combobox-input placeholder="Select a framework" aria-label="Framework"></ui-combobox-input>
      <ui-combobox-content>
        <ui-combobox-empty>No items found.</ui-combobox-empty>
        <ui-combobox-list>
          ${frameworks.map((item) => html`<ui-combobox-item value=${item}>${item}</ui-combobox-item>`)}
        </ui-combobox-list>
      </ui-combobox-content>
    </ui-combobox>
  `;
}
View Code

Auto Highlight

The combobox always highlights the first match as you type, so Enter picks it.

No items found.
Next.js
SvelteKit
Nuxt.js
Remix
Astro
import { html } from '@webjsdev/core';

const frameworks = ['Next.js', 'SvelteKit', 'Nuxt.js', 'Remix', 'Astro'];

// Typing highlights the first match on its own, so there is nothing to set.
export default function ComboboxAutoHighlight() {
  return html`
    <ui-combobox>
      <ui-combobox-input placeholder="Select a framework" aria-label="Framework"></ui-combobox-input>
      <ui-combobox-content>
        <ui-combobox-empty>No items found.</ui-combobox-empty>
        <ui-combobox-list>
          ${frameworks.map((item) => html`<ui-combobox-item value=${item}>${item}</ui-combobox-item>`)}
        </ui-combobox-list>
      </ui-combobox-content>
    </ui-combobox>
  `;
}
View Code

The combobox opens from its own input, and does not take a button trigger. To open a searchable list from a button, put a Command in a Popover, with the search field inside the popup, and listen for ui-select to show the choice on the button.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { popoverContentClass } from '#components/ui/popover.ts';
import { ChevronDownIcon } from '#lib/ui/lucide.ts';

const countries = [
  { code: '', value: '', continent: '', label: 'Select country' },
  { code: 'ar', value: 'argentina', label: 'Argentina', continent: 'South America' },
  { code: 'au', value: 'australia', label: 'Australia', continent: 'Oceania' },
  { code: 'br', value: 'brazil', label: 'Brazil', continent: 'South America' },
  { code: 'ca', value: 'canada', label: 'Canada', continent: 'North America' },
  { code: 'cn', value: 'china', label: 'China', continent: 'Asia' },
  { code: 'co', value: 'colombia', label: 'Colombia', continent: 'South America' },
  { code: 'eg', value: 'egypt', label: 'Egypt', continent: 'Africa' },
  { code: 'fr', value: 'france', label: 'France', continent: 'Europe' },
  { code: 'de', value: 'germany', label: 'Germany', continent: 'Europe' },
  { code: 'it', value: 'italy', label: 'Italy', continent: 'Europe' },
  { code: 'jp', value: 'japan', label: 'Japan', continent: 'Asia' },
  { code: 'ke', value: 'kenya', label: 'Kenya', continent: 'Africa' },
  { code: 'mx', value: 'mexico', label: 'Mexico', continent: 'North America' },
  { code: 'nz', value: 'new-zealand', label: 'New Zealand', continent: 'Oceania' },
  { code: 'ng', value: 'nigeria', label: 'Nigeria', continent: 'Africa' },
  { code: 'za', value: 'south-africa', label: 'South Africa', continent: 'Africa' },
  { code: 'kr', value: 'south-korea', label: 'South Korea', continent: 'Asia' },
  { code: 'gb', value: 'united-kingdom', label: 'United Kingdom', continent: 'Europe' },
  { code: 'us', value: 'united-states', label: 'United States', continent: 'North America' },
];

// The combobox opens from its own input, so a list opened from a button is
// a Command in a Popover: the button shows the choice, and the search field
// sits inside the popup. Listen for `ui-select` to set the button's text.
export default function ComboboxPopup() {
  return html`
    <button type="button" popovertarget="combobox-popup" aria-haspopup="dialog" aria-expanded="false" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-64 justify-between font-normal')}>
      <span>${countries[0].label}</span>
      ${ChevronDownIcon()}
    </button>
    <div id="combobox-popup" popover role="dialog" aria-label="Select country" data-slot="popover-content" class=${cn(popoverContentClass({ align: 'start' }), 'w-64 p-0')}>
      <ui-command label="Countries">
        <ui-command-input placeholder="Search"></ui-command-input>
        <ui-command-list>
          <ui-command-empty>No items found.</ui-command-empty>
          ${countries.map((item) => html`<ui-command-item value=${item.value || 'none'}>${item.label}</ui-command-item>`)}
        </ui-command-list>
      </ui-command>
    </div>
  `;
}
View Code

Input Group

The input part renders its own Input Group, with the trigger as its addon, and does not take an addon of its own yet.

No timezones found.
Americas
(GMT-5) New York
(GMT-8) Los Angeles
(GMT-6) Chicago
(GMT-5) Toronto
(GMT-8) Vancouver
(GMT-3) São Paulo
Europe
(GMT+0) London
(GMT+1) Paris
(GMT+1) Berlin
(GMT+1) Rome
(GMT+1) Madrid
(GMT+1) Amsterdam
Asia/Pacific
(GMT+9) Tokyo
(GMT+8) Shanghai
(GMT+8) Singapore
(GMT+4) Dubai
(GMT+11) Sydney
(GMT+9) Seoul
import { html } from '@webjsdev/core';

const timezones = [
  {
    value: 'Americas',
    items: [
      '(GMT-5) New York',
      '(GMT-8) Los Angeles',
      '(GMT-6) Chicago',
      '(GMT-5) Toronto',
      '(GMT-8) Vancouver',
      '(GMT-3) São Paulo',
    ],
  },
  {
    value: 'Europe',
    items: [
      '(GMT+0) London',
      '(GMT+1) Paris',
      '(GMT+1) Berlin',
      '(GMT+1) Rome',
      '(GMT+1) Madrid',
      '(GMT+1) Amsterdam',
    ],
  },
  {
    value: 'Asia/Pacific',
    items: [
      '(GMT+9) Tokyo',
      '(GMT+8) Shanghai',
      '(GMT+8) Singapore',
      '(GMT+4) Dubai',
      '(GMT+11) Sydney',
      '(GMT+9) Seoul',
    ],
  },
];

// The input part renders its own input group, with the trigger as its one
// addon, and takes no addon of its own yet.
export default function ComboboxInputGroup() {
  return html`
    <ui-combobox>
      <ui-combobox-input placeholder="Select a timezone" aria-label="Timezone"></ui-combobox-input>
      <ui-combobox-content>
        <ui-combobox-empty>No timezones found.</ui-combobox-empty>
        <ui-combobox-list>
          ${timezones.map((group) => html`
            <ui-combobox-group>
              <ui-combobox-label>${group.value}</ui-combobox-label>
              ${group.items.map((item) => html`<ui-combobox-item value=${item}>${item}</ui-combobox-item>`)}
            </ui-combobox-group>
          `)}
        </ui-combobox-list>
      </ui-combobox-content>
    </ui-combobox>
  `;
}
View Code

RTL

To enable RTL support, see the RTL configuration guide.

لم يتم العثور على فئات.
التكنولوجيا
التصميم
الأعمال
التسويق
التعليم
الصحة
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { fieldClass, fieldLabelClass } from '#components/ui/field.ts';

const categories = ['technology', 'design', 'business', 'marketing', 'education', 'health'] as const;

const translations = {
  en: {
    dir: 'ltr',
    values: {
      label: 'Categories',
      placeholder: 'Add categories',
      empty: 'No categories found.',
      technology: 'Technology',
      design: 'Design',
      business: 'Business',
      marketing: 'Marketing',
      education: 'Education',
      health: 'Health',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      label: 'الفئات',
      placeholder: 'أضف فئات',
      empty: 'لم يتم العثور على فئات.',
      technology: 'التكنولوجيا',
      design: 'التصميم',
      business: 'الأعمال',
      marketing: 'التسويق',
      education: 'التعليم',
      health: 'الصحة',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      label: 'קטגוריות',
      placeholder: 'הוסף קטגוריות',
      empty: 'לא נמצאו קטגוריות.',
      technology: 'טכנולוגיה',
      design: 'עיצוב',
      business: 'עסקים',
      marketing: 'שיווק',
      education: 'חינוך',
      health: 'בריאות',
    },
  },
};

// The provider is the dir attribute: every part styles itself with logical
// properties, so dir="rtl" on the field flips the whole control. A chip
// shows its item's label, so the values stay the English keys.
export default function ComboboxRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <div role="group" data-slot="field" data-orientation="vertical" dir=${dir} lang=${lang} class=${cn(fieldClass(), 'mx-auto w-full max-w-xs')}>
      <label data-slot="field-label" for="combobox-rtl" class=${fieldLabelClass()}>${t.label}</label>
      <ui-combobox multiple value=${categories[0]}>
        <ui-combobox-chips>
          <ui-combobox-chips-input input-id="combobox-rtl" placeholder=${t.placeholder}></ui-combobox-chips-input>
        </ui-combobox-chips>
        <ui-combobox-content dir=${dir}>
          <ui-combobox-empty>${t.empty}</ui-combobox-empty>
          <ui-combobox-list>
            ${categories.map((item) => html`<ui-combobox-item value=${item}>${t[item]}</ui-combobox-item>`)}
          </ui-combobox-list>
        </ui-combobox-content>
      </ui-combobox>
    </div>
  `;
}
View Code

API Reference

Typing filters the list, the arrow keys highlight while focus stays in the input, and Enter picks. The choice lives in a real form control, one <input type="hidden" name> per chosen value, served by the server, so the form submits it with or without JavaScript.

Elements

ElementDescription
<ui-combobox>The root. Holds the value, the open state and the hidden form inputs.
<ui-combobox-input>The text field, a role="combobox" input in an input group with the trigger button and the optional clear button.
<ui-combobox-content>The popup, placed against the input, or against the chips box with multiple.
<ui-combobox-list>The role="listbox" holding the items.
<ui-combobox-item>One choice, a role="option" with a check mark when chosen.
<ui-combobox-empty>Shown when nothing matches the typed text.
<ui-combobox-group>A role="group" of items, named by its label, hidden when none of its items match.
<ui-combobox-label>A group heading.
<ui-combobox-separator>A divider between groups.
<ui-combobox-chips>The chips box for multiple. Draws one chip per chosen value, each with a remove button that names its value.
<ui-combobox-chips-input>The text field inside the chips box.

ui-combobox

AttributeTypeDefault
namestring-
valuestring, comma separated with multiple-
multiplebooleanfalse
disabledbooleanfalse
openboolean, reflectedfalse

From code, show() and hide() open and close the list, choose(value) picks an item, removeValue(value) drops one choice, and clear() drops them all.

ui-combobox-input

AttributeTypeDefault
placeholderstring-
input-idstring, the id a <label for> points at-
aria-labelstring, passed to the input-
show-trigger"true" | "false""true"
show-clearbooleanfalse

<ui-combobox-chips-input> takes the same placeholder, input-id and aria-label.

ui-combobox-content

AttributeTypeDefault
side"top" | "right" | "bottom" | "left""bottom"
align"start" | "center" | "end""start"
side-offsetnumber6
align-offsetnumber0

ui-combobox-item

AttributeTypeDefault
valuestringThe item's text
disabledbooleanfalse

Events

EventDetailFires
ui-value-change{ value: string }, or { value: string[] } with multipleWhen the choice changes.
ui-open-change{ open: boolean }When the list opens or closes.

Keyboard

ArrowDown and ArrowUp open the list and move the highlight, Enter picks the highlighted item, Escape closes, and Tab closes and moves on. With multiple, picking toggles an item and keeps the list open, and Backspace in an empty input removes the last chip. Leaving a single combobox puts the chosen item's label back in the input.