Combobox

Autocomplete input with a list of suggestions.

Usage

HTML + JavaScript

Step 1: Include the JavaScript files

You can either include the JavaScript file for all the components, or just the one for this component:

<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.0/dist/js/basecoat.min.js" defer></script>
<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.0/dist/js/combobox.min.js" defer></script>
Components with JavaScript Use the CLI combobox.js

Step 2: 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">
  <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" class="w-[240px]" />
  <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 framework 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-multiple="true" for multiple selection and data-auto-highlight="true" to highlight the first match while filtering.
<input type="text" role="combobox">
The editable control. It should include aria-expanded, aria-controls, and aria-autocomplete="list".
<div class="combobox-chips"> Multiple only
Wraps selected chips and the editable input in multiple mode.
<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 and data-empty for the empty message.
<div role="option" data-value="...">
Selectable option. Options can contain custom HTML; use data-label when the visible input should use different text than the rendered content.
<input type="hidden">
Submitted value. Single mode stores a string; multiple mode stores a JSON array.

JavaScript events

basecoat:initialized
Dispatched on the component after initialization.
basecoat:popover
Dispatched on document when the popup opens so other popup components can close.
change
Dispatched on selection changes with event.detail.value.

JavaScript methods

value
Gets or sets the selected value. Multiple mode uses an array.
select(value)
Selects an option by value.
deselect(value) Multiple only
Removes a selected value.
toggle(value) Multiple only
Toggles a selected value.
refresh()
Rescans options after changing children inside the existing role="listbox" element.
window.basecoat.refresh(combobox)
Calls the component refresh method through the global dispatcher.

Jinja and Nunjucks

Use the combobox() macro for Nunjucks or Jinja.

Use Nunjucks or Jinja macros Jinja macro Nunjucks macro 
{% call combobox(
  placeholder="Select a framework",
  listbox_attrs={"data-empty": "No framework found."}
) %}
  <div role="option" data-value="nextjs">Next.js</div>
  <div role="option" data-value="sveltekit">SvelteKit</div>
  <div role="option" data-value="nuxtjs">Nuxt.js</div>
{% endcall %}

Examples

Multiple

Groups

Custom Items

Invalid

Disabled

Auto Highlight

Top Side

RTL