Combobox
Pick one or several options from a list you can search. You write a <select>, as for a Select; canon.js turns it into a box that opens a list, shows several values as tags, and, if you ask for it, lets people search. The select keeps the value, so forms, required and validation work as usual, and without canon.js it is a plain Select. Specification: docs/components/combobox.md.
The comboboxes on this page stand alone, so each is named with aria-label. With a visible label, a combobox is part of a Field.
Size
data-size on the box or any container. Each row: the placeholder, a chosen option with groups in its list and a search field (data-search="list"), and several values. Click a box to open its list.
sm
md
lg
Without data-size
Search
Search is optional. Without it, the list works like a Select's: typing jumps to the option that starts with what was typed. With data-search="list" on the box, the list has a search field on top. Typing narrows the list to the options whose label or description contains what was typed, ignoring case and accents, and marks the match. Groups and separators with nothing left go too; with nothing at all, the list says so. Typing on the closed box opens the list and starts the search. Up and Down move through the options, Enter picks, Escape closes. Try "o", then "xyz".
Typing in the box
data-search="inline" on the box: people type in the box itself and the list opens under it, without a search field. With one value, the box shows its label and Escape undoes typing; with several, the field follows the tags and Backspace in an empty field removes the last one.
New values
data-creatable on the box (with a search): when no option has the name that was typed, the list offers to add it. The new value becomes an option of the select, chosen, and is submitted like the others; once it isn't chosen, it is gone.
Free values
Several values, typed in the box and new values allowed, but no options to choose from: a tag input. Only a placeholder and the values to start with are in the select. There is no list: Enter or a comma adds what was typed, and so does leaving the box; a pasted list with commas or line breaks adds each part. Backspace in the empty field removes the last value. Each value is an option of the select, so the form submits them all under its name. If your app adds options later, they appear as suggestions.
Options from your app
data-filter="none" on the box (with a search): canon.js doesn't filter. Instead it fires a canon-search event on the select (event.detail.query) when the list opens and as people type. Your app sets aria-busy="true" on the select while it loads (the list shows that it is loading), replaces the options, and removes aria-busy. Keep the chosen options in the select, or their values are lost.
Several values
multiple on the select. Chosen options show as tags in the box; picking in the list adds or removes one, and the list stays open. Each tag has a remove button. A data-seed on an option colors its tag, as it would color a Tag; an icon or avatar comes along.
Statuses
With multiple, data-intent on an option makes it a status (info, success, warning, danger): shown as a status tag in the list and in the box, as in a filter on a table. A status may start with a .canon-tag-dot or an icon.
A limit
data-max on the select: once that many are chosen, the other options can't be picked until one is removed.
One row
data-tags="collapse" on the box keeps the tags on one row: those that don't fit become "+N". The list and screen readers still have every value.
Wrapping
Tags wrap onto new rows and the box grows; the arrow stays on the last row.
Options
The same options as a Select: an icon or an avatar before the label, a description after it (searched too, shown only in the list), and disabled options. The box shows the chosen option's icon or avatar.
Box
Leading icon
Clear button
A canon-button with command="--canon-clear" and commandfor the select, after the select, clears every value (or goes back to the placeholder). It hides while there is nothing to clear; this theme also shows it only while the box is hovered or focused (always on touch screens), keeping its space so nothing moves. Point at a box below, or tab to it, to see the button appear before the arrow.
States
Error is aria-invalid="true" on the select; warning and success are data-intent on the box (in a Field, its message sets them). Disabled is the select's disabled.
Edge cases
Right-to-left
Long values in a narrow box
The box cuts a long value short, and so does a long tag; the list grows to fit its options, up to the window.