Combobox

Checkbox
Command

Combobox

Usage

Template macros available

This component ships a combobox() macro for Jinja and Nunjucks.

Include CSS

Import Tailwind and one full Basecoat style bundle.

@import "tailwindcss";
@import "basecoat-css/vega.css";

Or import only the base CSS, Combobox component CSS, and one style pack.

@import "tailwindcss";
@import "basecoat-css/base.css";
@import "basecoat-css/components/combobox.css";
@import "basecoat-css/styles/vega.css";

Using CDN or bundler imports? See the Installation page.

Include JavaScript

Copy or serve the full Basecoat JavaScript bundle.

<script src="/assets/js/all.min.js" defer></script>

Or copy or serve the Basecoat runtime and Combobox script.

<script src="/assets/js/basecoat.min.js" defer></script>
<script src="/assets/js/combobox.min.js" defer></script>

Using CDN or bundler imports? See the Installation page.

Add your combobox HTML

Combobox is input-first. The visible input filters the list; the hidden input stores the submitted value.

<div id="framework-combobox" class="combobox w-[240px]">
  <input type="text" role="combobox" placeholder="Select a framework" autocomplete="off" autocorrect="off" spellcheck="false" aria-autocomplete="list" aria-expanded="false" aria-controls="framework-combobox-listbox" /><svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="combobox-trigger-icon"><path d="m6 9 6 6 6-6" /></svg>
  <div id="framework-combobox-popover" data-popover aria-hidden="true">
    <div role="listbox" id="framework-combobox-listbox" aria-orientation="vertical" data-empty="No items found.">
      <div role="option" data-value="Next.js">Next.js</div>
      <div role="option" data-value="SvelteKit">SvelteKit</div>
      <div role="option" data-value="Nuxt.js">Nuxt.js</div>
      <div role="option" data-value="Remix">Remix</div>
      <div role="option" data-value="Astro">Astro</div>
    </div>
  </div>
  <input type="hidden" name="framework" value="" />
</div>

HTML structure

<div class=“combobox”>

Root element. Add data-auto-highlight=“true” to make the first visible option active when the list opens or filters. Add data-format=“object” to serialize selected values as objects. Add data-filter=“manual” when your app owns filtering.

<input type=“text” role=“combobox”>
The editable control. It can be a direct child, inside .input-group, or inside data-popover for popup mode.
<button aria-haspopup=“listbox”> Optional
Opens the list from an input group or popup trigger. In popup mode, include a child with data-value and optional data-placeholder to display the selected value.
<button data-clear> Optional
Clears the current selection. Put the clear icon inside the button.
<svg class=“combobox-trigger-icon”> Optional
Decorative trailing icon for input-style comboboxes. Replace the SVG to customize the icon.
<div data-popover>
The suggestions popup. Use data-side and data-align like Popover.
<div role=“listbox”>
The suggestions list. Add aria-multiselectable=“true” in multiple mode. The component uses that attribute to render selected chips around the input.
<div role=“option” data-value=”…”>
Selectable option. Options can contain custom HTML; use data-label when the input should display different text than the rendered content.
<input type=“hidden”>
Submitted value. Single mode stores a string; multiple mode stores a JSON array. With data-format=“object”, selected values are stored as objects.

JavaScript API

APITypeDescription
changeEventDispatched on selection changes with event.detail.value and event.detail.selected.
combobox.setValue(value)MethodSets the selected value from a plain value or { value, label } object.
combobox.clear()MethodClears the selected value.
combobox.refresh()MethodRescans options after children change inside the existing role="listbox" element.

Examples

Multiple

Clear button

Groups

Custom items

Invalid

Select a framework to continue.

Disabled

Auto highlight

Auto highlight makes the first visible option active when the list opens or filters, so pressing Enter can select it without arrowing first.

Input group

RTL