---
layout: layouts/page.njk
title: Combobox
description: Autocomplete input and command palette with a list of suggestions.
toc:
- label: Usage
id: usage
children:
- label: HTML + JavaScript
id: usage-html-js
children:
- label: "Step 1: Include the JavaScript files"
id: usage-html-js-1
- label: "Step 2: Add your combobox HTML"
id: usage-html-js-2
- label: HTML structure
id: usage-html-js-3
- label: Jinja and Nunjucks
id: usage-macro
- label: Examples
id: examples
children:
- label: Scrollable
id: example-scrollable
- label: Top side
id: example-top
---
{% from "macros/code_preview.njk" import code_preview %}
{% from "macros/code_block.njk" import code_block %}
{% from "select.njk" import select %}
{% set options_frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"] %}
{% set code_html %}
{% call select(
trigger_attrs={"class": "w-[200px]"},
listbox_attrs={"data-empty": "No framework found."},
is_combobox=true,
search_placeholder="Search framework..."
) %}
{% for framework in options_frameworks %}
{{ framework }}
{% endfor %}
{% endcall %}
{% endset %}
{{ code_preview("combobox", code_html | prettyHtml) }}
{% set code_script %}{% endset %}
{{ code_block(code_script | prettyHtml, "html") }}
Combobox uses the same markup and JavaScript as the Select component, the only difference being the search box at the top of the listbox:
{{ code_block(code_html | prettyHtml, "html") }}
<div class="select">
- Wraps around the entire component.
<button type="button" popovertarget="{ POPOVER_ID }">
-
The trigger to open the popover, can also have the following attributes:
id="{BUTTON_ID}": linked to by the aria-labelledby attribute of the listbox.
aria-haspopup="listbox": indicates that the button opens a listbox.
aria-controls="{ LISTBOX_ID }": points to the listbox's id.
aria-expanded="false": tracks the popover's state.
aria-activedescendant="{ OPTION_ID }": points to the active option's id.
<div popover class="popover" id="{ POPOVER_ID }">
- As with the Popover component, you can set up the side and alignment of the popover using the
data-side and data-align attributes.
<header>
- Contains the search input to filter the options in the listbox.
<div role="listbox">
- The listbox containing the options. Should have the following attributes:
id="{ LISTBOX_ID }": refered to by the aria-controls attribute of the trigger.
aria-labelledby="{ BUTTON_ID }": linked to by the button's id attribute.
<div role="option" data-value="{ VALUE }">
- Option that can be selected.Should have a unique id if you use the
aria-activedescendant attribute on the trigger.
<hr role="separator"> Optional
- Separator between groups/options.
<div role="group"> Optional
- Group of options, can have a
aria-labelledby attribute to link to a heading.
<span role="heading">
- Group heading, must have an
id attribute if you use the aria-labelledby attribute on the group.
<input type="hidden" name="{ NAME }" value="{ VALUE }"> Optional
- The hidden input that holds the value of the field (if needed).
You can use the select() Nunjucks or Jinja macro for this component. If you use one of the macros, make sure to set is_combobox to True (or true for Nunjucks).
{% set raw_code %}{% raw %}{% call select(
listbox_attrs={"data-empty": "No framework found."},
is_combobox=true
) %}
Next.js
SvelteKit
Nuxt.js
Remix
Astro
{% endcall %}{% endraw %}{% endset %}
{{ code_block(raw_code, "jinja") }}
{% set options_timezones = [
{
label: "Americas",
timezones: [
{ value: "America/New_York", label: "(GMT-5) New York" },
{ value: "America/Los_Angeles", label: "(GMT-8) Los Angeles" },
{ value: "America/Chicago", label: "(GMT-6) Chicago" },
{ value: "America/Toronto", label: "(GMT-5) Toronto" },
{ value: "America/Vancouver", label: "(GMT-8) Vancouver" },
{ value: "America/Sao_Paulo", label: "(GMT-3) São Paulo" }
]
},
{
label: "Europe",
timezones: [
{ value: "Europe/London", label: "(GMT+0) London" },
{ value: "Europe/Paris", label: "(GMT+1) Paris" },
{ value: "Europe/Berlin", label: "(GMT+1) Berlin" },
{ value: "Europe/Rome", label: "(GMT+1) Rome" },
{ value: "Europe/Madrid", label: "(GMT+1) Madrid" },
{ value: "Europe/Amsterdam", label: "(GMT+1) Amsterdam" }
]
},
{
label: "Asia/Pacific",
timezones: [
{ value: "Asia/Tokyo", label: "(GMT+9) Tokyo" },
{ value: "Asia/Shanghai", label: "(GMT+8) Shanghai" },
{ value: "Asia/Singapore", label: "(GMT+8) Singapore" },
{ value: "Asia/Dubai", label: "(GMT+4) Dubai" },
{ value: "Australia/Sydney", label: "(GMT+11) Sydney" },
{ value: "Asia/Seoul", label: "(GMT+9) Seoul" }
]
}
] %}
{% set code %}
{% call select(
trigger_attrs={"class": "w-[200px]"},
popover_attrs={"class": "w-72"},
listbox_attrs={"data-empty": "No timezone found."},
is_combobox=true,
search_placeholder="Search timezone..."
) %}
{% lucide "circle-plus" %}
Create timezone
{% endcall %}
{% endset %}
{{ code_preview("combobox-with-groups", code | prettyHtml) }}
{% set options_frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"] %}
{% set code %}
{% call select(
trigger_attrs={"class": "w-[200px]"},
listbox_attrs={"data-empty": "No framework found."},
is_combobox=true,
search_placeholder="Search framework...",
popover_attrs={"data-side": "top"}
) %}
{% for framework in options_frameworks %}
{{ framework }}
{% endfor %}
{% endcall %}{% endset %}
{{ code_preview("combobox", code | prettyHtml) }}