# auro-combobox ## Properties | Property | Attribute | Type | Default | Description | |---------------------|---------------------|-----------|-------------|--------------------------------------------------| | [checkmark](#checkmark) | `checkmark` | `Boolean` | | When attribute is present auro-menu will apply checkmarks to selected options. | | [disabled](#disabled) | `disabled` | `Boolean` | | If set, disables the combobox. | | [error](#error) | `error` | `Boolean` | | Sets a persistent error state (e.g. an error state returned from the server). | | [noFilter](#noFilter) | `noFilter` | `Boolean` | false | If set, combobox will not filter menuoptions based in input. | | [noValidate](#noValidate) | `noValidate` | `Boolean` | | If set, disables auto-validation on blur. | | [optionSelected](#optionSelected) | `optionSelected` | `Object` | null | Specifies the current selected option. | | [required](#required) | `required` | `Boolean` | | Populates the `required` attribute on the input. Used for client-side validation. | | [setCustomValidity](#setCustomValidity) | `setCustomValidity` | `String` | | Sets a custom help text message to display for all validityStates. | | [triggerIcon](#triggerIcon) | `triggerIcon` | `Boolean` | | If set, the `icon` attribute will be applied to the trigger `auro-input` element. | | [type](#type) | `type` | `String` | | Applies the defined value as the type attribute on auro-input. | | [validity](#validity) | `validity` | `String` | "undefined" | Specifies the `validityState` this element is in. | | [value](#value) | `value` | `String` | null | Value selected for the dropdown menu. | ## Methods | Method | Type | Description | |---------|------------|-------------------------------------| | [focus](#focus) | `(): void` | Focuses the combobox trigger input. | ## Events | Event | Type | Description | |-----------------------------|--------------------|--------------------------------------------------| | `auroCombobox-ready` | `CustomEvent` | Notifies that the component has finished initializing. | | `auroCombobox-valueSet` | `CustomEvent` | Notifies that the component has a new value set. | | `auroFormElement-validated` | | Notifies that the component value(s) have been validated. | ## Slots | Name | Description | |------------|--------------------------------------| | | Default slot for the menu content. | | [helpText](#helpText) | Defines the content of the helpText. | | [label](#label) | Defines the content of the label. | ## API Examples ### Basic
Name Apples Oranges Peaches Grapes Cherries No matching option
See code ```html Name Apples Oranges Peaches Grapes Cherries No matching option ``` ### Dynamic Menu This example demonstrates a data driven combobox. The data is used to populate the `auro-menu`. In this example, each time the input's value changes, the data is updated and the menu is recreated. The menu in this example was populated from data from a country/city API. To keep the data set small, the data in the menu is based off an API call that returns all countries and cities that contain the substring "**germ**" (non case-sensitive) in their name.
Name
See code ```html Name ``` ```js // Javascript example file // ----------------------- import { DynamicData } from './dynamicMenuDataApi'; export function dynamicMenuExample() { // Resets the root menu function resetMenu(root) { while (root.firstChild) { root.removeChild(root.firstChild); } } // Generates HTML for menu and submenus using country & city data from an external API function generateHtml(data) { const initialMenu = document.querySelector('#initMenu'); resetMenu(initialMenu); for (let index = 0; index < data.length; index++) { let country = data[index]['country']; let cities = data[index]['cities']; generateMenuOptionHtml(initialMenu, country, country); for (let indexB = 0; indexB < cities.length; indexB++) { let subMenu = document.createElement('auro-menu'); generateMenuOptionHtml(subMenu, cities[indexB], cities[indexB]); initialMenu.appendChild(subMenu); } }; } // Helper function that generates HTML for menuoptions function generateMenuOptionHtml(menu, label, value) { let option = document.createElement('auro-menuoption'); option.value = value; option.innerHTML = label; menu.appendChild(option); } // Main javascript that runs all JS to create example const dynamicData = new DynamicData(); const dynamicMenuExample = document.querySelector('#dynamicMenuExample'); const dropdownEl = dynamicMenuExample.shadowRoot.querySelector(dynamicMenuExample.dropdownTag._$litStatic$); const inputEl = dropdownEl.querySelector(dynamicMenuExample.inputTag._$litStatic$); inputEl.addEventListener('input', () => { let data = dynamicData.getData(); data = dynamicData.filterData(data, dynamicMenuExample.value); generateHtml(data); }); } ``` ### Property Examples #### disabled If set, disables the combobox.
Name Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option
See code ```html Name Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option ``` #### noFilter If set, combobox will not do suggestion filtering of the menuoptions. This option is useful when the `` elements are being pre-filtered externally to combobox (e.g. using the citysearch API).
Name Apples Oranges Peaches Grapes Cherries No matching option
See code ```html Name Apples Oranges Peaches Grapes Cherries No matching option ``` #### error Sets a persistent error state (e.g. an error state returned from the server).
Name Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option
See code ```html Name Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option ``` #### noValidate Intended for use with the `required` attribute. If set, disables auto-validation on blur. By using these two attributes in combination the validation for required fields is still computed for forms but no validation messaging will be generated in the UI.
Name Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option
See code ```html Name Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option ``` #### required Populates the `required` attribute on the input. Used for client-side validation.
Name Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option
See code ```html Name Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option ``` #### value Use the `value` attribute to programmatically set the value of the combobox.
Name Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option
See code ```html Name Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option ``` #### Dynamically Set Value Use the `value` attribute in combination with another element to dynamically set the value of the combobox. Can be used in the following ways: * Preset the value of the combobox to valid menu option * Set the value of the combobox to invalid menu option * Reset the value of the combobox to undefined Note: using a value that does not match a menu option will reset the combobox value to undefined.
Set to an existing option Set to custom value Reset

Name Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option
See code ```html Set to an existing option Set to custom value Reset

Name Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option ``` ```js export function valueExample() { const valueExample = document.querySelector('#valueExample'); document.querySelector('#valueValidExampleBtn').addEventListener('click', () => { valueExample.value = 'Oranges'; }); document.querySelector('#valueInvalidExampleBtn').addEventListener('click', () => { valueExample.value = 'Dragon Fruit'; }); document.querySelector('#valueUndefinedExampleBtn').addEventListener('click', () => { valueExample.value = undefined; }); } ``` #### type When defined, the `auro-input` in the combobox trigger will use the defined `type` (e.g. `credit-card`).
Date 01/02/2020 05/16/2022
See code ```html Date 01/02/2020 05/16/2022 ``` ### Method Examples #### focus The focus method will apply focus state to the combobox input field.
Apply focus to combobox

Name Apples Oranges Peaches Grapes Cherries No matching option
See code ```js export function focusExample() { const focusExample = document.querySelector('#focusExample'); const focusExampleBtnElem = document.querySelector('#focusExampleBtn'); focusExampleBtnElem.addEventListener('click', () => { focusExample.focus(); }); } ``` ```html Apply focus to combobox

Name Apples Oranges Peaches Grapes Cherries No matching option ``` ### Slot Examples #### helpText Sets the help text displayed below the trigger. The `helpText` slot can be used to provide additional context for the combobox. When using the `error` property, the `helpText` slot can be used to describe the error.
Name Custom help text Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option
See code ```html Name Custom help text Apples Oranges Peaches Grapes Cherries Prefer Alaska No matching option ```