Combo Box

Example

<vega-combo-box
    required=true
    label="label text"
    id="my-combo-box"

>
</vega-combo-box>

const comboBox = document.getElementById('my-combo-box');
comboBox.source = [
    { key: 'key1', label: 'option 1' },
    { key: 'key2', label: 'option 2' },
    { key: 'key3', label: 'option 3' },
];

Example with createable options

<vega-combo-box
    required=true
    label="label text"
    id="my-combo-box"

>
</vega-combo-box>

const comboBox = document.getElementById('my-combo-box');
comboBox.source = [
    { key: 'key1', label: 'option 1' },
    { key: 'key2', label: 'option 2' },
    { key: 'key3', label: 'option 3' },
];

comboBox.vegaDropdownProps = {
    dynamicOption : true
}
comboBox.addEventListener('vegaCreate', (e) => {
        comboBox.source.push({key: e.detail, label: e.detail}); 
        comboBox.value = [...comboBox.value, e.detail]
    })

Usage

The combo box is similar to an input field, but allows inclusion of chips within the field. It mimics the select box for dropdown items, but will allow selecting and adding multiple chips.

These are ideally used when there is a need for multiple entries to show as chosen within an input. A common use case might be an email “to” field.

As shown in the second example above, it is possible to allow users to create new chips for the Combo Box.

Properties

All Parameters

<vega-combo-box
    required=true|false
    label='string'
    value='array of item keys: [key1, key2...]'
    auto-validation=true|false
    validation-rules='Rules'
    disabled=true|false
    placeholder='string'
    hint='string'
    size='small|medium'
    source='array of items: [{key: key1, label: label1}, {key: key2, label: label2}...]'
    vega-dropdown-props: {
        maxHeight: 'number',
        matchContainerHeight: true|false,
        positionRelativeTo: 'selector of scroll container',
		dynamicOption: true|false,
		isLoading: true|false,
    },
	use-default-filter=true|false
>
</vega-combo-box>

Create New Item

To have the vega-combo-box create a new item, set vegaDropdownProps.dynamicOption as true. When searching for an item, if no match is found, the text “Add {search string}” will display. Clicking on this text will emit a vegaCreate event with the search string as the parameter.

While receiving this event, you can generate a key and create it as a DropdownSourceItem and you may also set it as a source, and push the key to a value.

Note: When pushing a new item to the array or to change the value, it is important to use a new array with the new item, or the UI will not update.

Example:

<VegaComboBox
    source={this.source}
    value={this.value}
    onVegaCreate={ (e) => {
        const key = "You should generate key by backend or other ways";
        this.source = [...this.source, {
            key: key,
            label: e.detail
        }];
        this.value = [...this.value, key];
    }}
    ...
></VegaComboBox>

Event

When the value of vega-combo-box is changed, it dispatches the vegaChange event.

document.getElementById("my-combo-box").addEventListener("vegaChange", (e) => {
console.log(e.currentTarget.value) })

When the validation result of vega-combo-box is changed, it will dispatch the vegaValidate event.

document.getElementById("my-combo-box").addEventListener("vegaValidate", (e) => {
console.log(e.currentTarget.isValid) })

When dynamicOption is set to true and an item is added in the dropdown, it will dispatch the vegaCreate event.

document.getElementById("my-combo-box").addEventListener("vegaCreate", (e) => { console.log(e.detail) })

When userDefaultFilter is false and type the search input, the event of vegaSearch will be dispatched.

document.getElementById("my-combo-box").addEventListener("vegaSearch", (e) => { console.log(e.detail) });

For more details (including examples in React and Vue), view in Storybook

Accessibility

• ARIA commands must have an accessible name
• Required ARIA attributes must be provided
• ARIA roles used must conform to valid values
• Inline text spacing must be adjustable with custom stylesheets
• Elements must have sufficient color contrast
• id attribute value must be unique
• Form field must not have multiple label elements
• Form elements must have labels

Best Practices

Use the combo box whenever there are instances where you want users to be able to select multiple items from a list but where these choices should be finite. Follow the same guidelines provided for chips.