Usage

You can either include the JavaScript file for all the components, or just the one for this component by adding this to the <head> of your page:

Step 2: Add your combobox 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:

HTML structure

<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. Optional attributes:

data-filter: custom text used for filtering (if different from displayed content, e.g., data-filter="united states")
data-keywords: additional keywords for enhanced filtering (e.g., data-keywords="bread fruit")
data-force: forces the option to always display, regardless of filter (e.g., data-force)
aria-disabled="true": marks option as disabled (excluded from selection and keyboard navigation)

<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).

JavaScript events

basecoat:initialized: Once the component is fully initialized, it dispatches a custom (non-bubbling) basecoat:initialized event on itself.
basecoat:popover: When the popover opens, the component dispatches a custom (non-bubbling) basecoat:popover event on document. Other popover components (Combobox, Dropdown Menu, Popover and Select) listen for this to close any open popovers.
change: When the selected value changes, the component dispatches a custom (bubbling) change event on itself, with the selected value in event.detail (e.g. {detail: {value: "something"}}).

JavaScript methods

selectByValue: You can call this method on the component after it is initialized to select an option by value (i.e. the option with the matching data-value attribute):
{% set code_script %}{% endset %} {{ code_block(code_script | prettyHtml, "html") }}

Jinja and Nunjucks

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).

Examples

{% for group in options_timezones %}

{% for timezone in group.timezones %} {% endfor %}

{% endfor %}

Usage

HTML + JavaScript

Step 1: Include the JavaScript files