> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/lwc-components/core-components/combobox.md). # Combobox `avonni-combobox` A widget that provides a user with an input field that is either an autocomplete or readonly, accompanied by a listbox of options. ## Overview **Combobox** is a Lightning Web Component that lets users select one or more options from a searchable, groupable dropdown, with support for scopes, nested levels, actions, and selected-option pills. Use it in your own Lightning Web Components for single- or multi-select pickers that go beyond a basic dropdown. You control the options, grouping, search, multi-select limits, scopes, and inline actions—all through the component's attributes. Reference `` in your component's HTML template to use it. ### Use Cases * **Record assignment:** Pick an owner or assignee from a grouped people list. * **Multi-select tagging:** Let users apply several tags with selectable pills. * **Scoped search:** Filter options by a scope (e.g. "My team" vs "All teams"). * **Nested navigation:** Drill into multi-level option hierarchies. * **Inline actions:** Offer a "Create new" action at the end of the options. *** ## Use Case Examples ### Example 1: Single-select with scopes and groups **Scenario:** Assign a record to a team member, grouped by team, with a scope selector to filter between all teams and the current user's team. ```html ``` ```js // assignOwner.js import { LightningElement } from 'lwc'; export default class AssignOwner extends LightningElement { groups = [ { name: 'engineering', label: 'Engineering' }, { name: 'design', label: 'Design' } ]; people = [ { label: 'Ada Lovelace', value: 'ada', secondaryText: 'Principal Engineer', groups: ['engineering'] }, { label: 'Grace Hopper', value: 'grace', secondaryText: 'Design Lead', groups: ['design'] } ]; scopes = [ { label: 'All teams', value: 'all', iconName: 'utility:company' }, { label: 'My team', value: 'mine', iconName: 'utility:people' } ]; scopeValue = 'all'; assignee = 'ada'; handleChange(event) { const value = event.detail.value; // selected option value } handleScopeChange(event) { const scope = event.detail.value; // 'all' or 'mine' } } ``` **Result:** A grouped, scoped picker; selecting a person fires `change` and changing the scope fires `scopechange`. ### Example 2: Multi-select tags with an action **Scenario:** Let users apply multiple tags with search enabled and a "Create new tag" action at the end of the list. ```html ``` ```js // tagPicker.js import { LightningElement } from 'lwc'; export default class TagPicker extends LightningElement { tags = [ { label: 'High priority', value: 'high', secondaryText: 'Needs attention this sprint' }, { label: 'Bug', value: 'bug', secondaryText: 'Defect to be fixed' } ]; actions = [{ label: 'Create new tag', name: 'create', iconName: 'utility:add', fixed: true }]; selectedTags = ['high', 'bug']; handleChange(event) { const values = event.detail.value; // array of selected values } handleActionClick(event) { if (event.detail.name === 'create') { // open a create-tag flow } } } ``` **Result:** A multi-select combobox with searchable options, selected pills, and a fixed action; selecting tags fires `change`, and clicking the action fires `actionclick`. *** ## Specifications ### Attributes | Name | Description | Type | Default | Required | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------- | -------- | | `actions` | Array of action objects. The actions are displayed at the end of the combobox options. | AvonniComboboxAction\[] | — | | | `allow-search` | If present, the combobox options are searchable. | Boolean | `false` | | | `back-action` | Action object. The back action is used to go back to the previous level, after clicking on an option that has nested options. | AvonniComboboxAction | — | | | `disabled` | If present, the combobox is disabled and users cannot interact with it. | Boolean | `false` | | | `dropdown-alignment` | Specifies where the drop-down list is aligned with or anchored to the selection field. Valid values include auto, left, center, right, bottom-left, bottom-center and bottom-right. By default the list is aligned with the selection field at the top left so the list opens down. Use bottom-left to make the selection field display at the bottom so the list opens above it. Use auto to let the component determine where to open the list based on space available. | String | `"left"` | | | `dropdown-length` | Maximum length of the dropdown menu. Valid values include 5-items, 7-items and 10-items. | String | `"7-items"` | | | `field-level-help` | Help text detailing the purpose and function of the combobox. | String | — | | | `groups` | Array of group objects. The groups are used to separate the options inside the drop-down. | AvonniComboboxGroup\[] | — | | | `hide-avatar-in-selected-options` | If present, the avatar will be hidden in selected options. | Boolean | `false` | | | `hide-clear-icon` | If present, it is not possible to clear a selected option using the input clear icon. | Boolean | `false` | | | `hide-options-until-search` | If present, the combobox options are hidden until a search value is entered. | Boolean | `false` | | | `hide-selected-options` | If present, the selected options pills will be hidden. | Boolean | `false` | | | `is-loading` | If true, the drop-down menu is in a loading state and shows a spinner. | Boolean | `false` | | | `is-multi-select` | If present, multiple options can be selected. | Boolean | `false` | | | `keep-open-on-select` | If present, the dropdown menu will remain open after an option is selected. | Boolean | `false` | | | `label` | Text label for the combobox. | String | — | | | `loading-state-alternative-text` | Message displayed while the combobox is in the loading state. | String | `"Loading"` | | | `max` | If multi-select, maximum number of selected options allowed. | Number | — | | | `message-when-bad-input` | Error message to be displayed when a bad input is detected. | String | — | | | `message-when-range-overflow` | Error message to be displayed when a range overflow is detected. | String | — | | | `message-when-range-underflow` | Error message to be displayed when a range underflow is detected. | String | — | | | `message-when-value-missing` | Error message to be displayed when the value is missing and input is required. | String | — | | | `min` | If multi-select, minimum number of selected options allowed. | Number | `0` | | | `multi-level-groups` | If present, groups can contain other groups. Each group added to an option will create a level of depth. If false, there will be only one level of groups. If an option belongs to several groups, the option will be repeated in each group. | Boolean | `false` | | | `name` | Specifies the name of the combobox. | String | — | | | `no-results-message` | Message displayed when no search results are found. | String | `"No matches found"` | | | `options` | Array of option objects. | AvonniComboboxOption\[] | — | | | `placeholder` | Text that is displayed before an option is selected, to prompt the user to select an option. The default value varies depending on the value of allow-search. | String | `"Select an option -or- Search…"` | | | `read-only` | If present, the combobox is read-only. A read-only combobox is also disabled. | Boolean | `false` | | | `remove-selected-options` | If present, the selected options will be removed from the options. If false, a checkmark will be displayed next to the selected options. | Boolean | `false` | | | `required` | If present, a value must be selected before the form can be submitted. | Boolean | `false` | | | `required-alternative-text` | The assistive text when the required attribute is set to true. | String | `"Required"` | | | `scope-value` | Value of the selected scope. | String | — | | | `scopes` | Array of scope objects. The scopes are displayed in a drop-down menu, to the left of the combobox input. | AvonniComboboxScope\[] | — | | | `scopes-groups` | Array of group objects. The groups are used to separate the scopes inside the drop-down. | AvonniComboboxGroup\[] | — | | | `selected-options-aria-label` | Describes the selected options section to assistive technologies. | String | `"Selected Options"` | | | `selected-options-direction` | Direction of the selected options. Horizontally, the selected options will be displayed as pills. Vertically, the selected options will be displayed as a list. | String | `"horizontal"` | | | `show-selected-options-secondary-text` | If present, the secondary text of the selected options is displayed. | Boolean | `false` | | | `sortable-selected-options` | If present, the selected options are sortable. | Boolean | `false` | | | `sortable-selected-options-icon-name` | The Lightning Design System name of the icon indicating that the selected options are sortable. Specify the name in the format 'utility:user' where 'utility' is the category, and 'user' is the specific icon to be displayed. The icon is visible only if `sortable-selected-options` is present, and selected-options-direction is vertical. | String | — | | | `validity` | Represents the validity states that an element can be in, with respect to constraint validation. | String | — | | | `value` | Array of selected options value, or unique string value. If is-multi-select is false and several values are passed, only the first one will be taken into account. | (string\[] | string) | — | | `variant` | The variant changes the appearance of the combobox. Accepted variants include standard, label-hidden, label-inline, and label-stacked. This value defaults to standard. Use label-hidden to hide the label but make it available to assistive technology. Use label-inline to horizontally align the label and combobox. Use label-stacked to place the label above the combobox. | String | `"standard"` | | ### Methods | Name | Description | Argument Name | Argument Type | Argument Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------- | ----------------------------------------------------------------------------------------------- | | `blur` | Remove focus from the combobox. | | | | | `checkValidity` | Check if the input is valid. | | | | | `close` | Close the drop-down. | | | | | `focus` | Set focus on the combobox. | | | | | `open` | Open the drop-down. | | | | | `reportValidity` | Display the error messages. If the input is valid, `reportValidity()` clears displayed error messages. | | | | | `resetLevel` | Reset the combobox to the first options level. | | | | | `setCustomValidity` | Set a custom error message to be displayed when a form is submitted. | `message` | String | The string that describes the error. If message is an empty string, the error message is reset. | | `showHelpMessageIfInvalid` | Display error messages on invalid fields. An invalid field fails at least one constraint validation and returns false when `checkValidity()` is called. | | | | | `updateScope` | Update the scope drop-down value. | `value` | String | Unique value of the scope that should be selected. | ### Custom Events #### `actionclick` The event fired when a user clicks on an action. The `actionclick` event returns the following parameters. | Parameter | Type | Description | | --------- | ------ | ------------------------------- | | `name` | string | The name of the action clicked. | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | true | This event bubbles up through the DOM. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | false | This event does not propagate outside of the component in which it was dispatched. | #### `backactionclick` The event fired when a user clicks on a back action. The `backactionclick` event doesn't return any parameters. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | true | This event bubbles up through the DOM. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | false | This event does not propagate outside of the component in which it was dispatched. | #### `blur` The event fired when the focus is removed from the combobox. The `blur` event doesn't return any parameters. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | false | This event does not bubble. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | false | This event does not propagate outside of the component in which it was dispatched. | #### `change` The event fired when the combobox value changes. The value changes when an option has been selected or unselected, or because the selected options have been reordered. The `change` event returns the following parameters. | Parameter | Type | Description | | ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `action` | string | Type of change made to the value. Options are `select`, `unselect` or `reorder`. | | `levelPath` | number\[] | If an option has been selected or unselected, array of level indexes to get to the option. This is useful in case options are nested. The levels start at 0. For example, if an option is the third child of its parent, and its parent is the second child of the root options, the value would be: `[1, 2]`. | | `value` | (string\[] | string) | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | true | This event bubbles up through the DOM. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | false | This event does not propagate outside of the component in which it was dispatched. | #### `close` The event fired when the drop-down is closed. It is not fired when the drop-down is closed programmatically with the `close()` method. The `close` event doesn't return any parameters. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | false | This event does not bubble. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | false | This event does not propagate outside of the component in which it was dispatched. | #### `focus` The event fired when the focus is set on the combobox. The `focus` event doesn't return any parameters. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | false | This event does not bubble. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | false | This event does not propagate outside of the component in which it was dispatched. | #### `levelchange` The event fired when an option with nested options has been selected. The `levelchange` event returns the following parameters. | Parameter | Type | Description | | --------- | ------ | --------------- | | `option` | object | Option clicked. | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | true | This event bubbles up through the DOM. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | false | This event does not propagate outside of the component in which it was dispatched. | #### `loadmore` The event fired when you scroll to the bottom of the drop-down to load more options. The `loadmore` event returns the following parameters. | Parameter | Type | Description | | ------------ | ------ | --------------------------------------------------------- | | `option` | object | Current parent option, if the visible options are nested. | | `searchTerm` | string | Value of the search input. | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | false | This event does not bubble. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | false | This event does not propagate outside of the component in which it was dispatched. | #### `open` The event fired when the drop-down is opened. It is not fired when the drop-down is opened programmatically with the `open()` method. The `open` event doesn't return any parameters. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | false | This event does not bubble. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | false | This event does not propagate outside of the component in which it was dispatched. | #### `scopechange` The event fired when a scope is selected. The `scopechange` event returns the following parameters. | Parameter | Type | Description | | --------- | ------ | -------------------------------- | | `value` | string | The value of the scope selected. | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | true | This event bubbles up through the DOM. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | false | This event does not propagate outside of the component in which it was dispatched. | #### `search` The event fired when a user types into the combobox input. The `search` event returns the following parameters. | Parameter | Type | Description | | --------- | ------ | --------------------------------------------------------- | | `option` | object | Current parent option, if the visible options are nested. | | `value` | string | The value of the search input. | The event properties are as follows. | Property | Value | Description | | ---------- | ----- | --------------------------------------------------------------------------------------------------------- | | bubbles | false | This event does not bubble. | | cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. | | composed | false | This event does not propagate outside of the component in which it was dispatched. | ### Styling Hooks | CSS Variable | Type | Default | | ------------------------------------------------------------------------- | --------- | ------------- | | `--avonni-combobox-action-color-background` | color | `transparent` | | `--avonni-combobox-action-color-background-disabled` | color | `transparent` | | `--avonni-combobox-action-color-background-hover` | color | `#f3f2f2` | | `--avonni-combobox-action-text-color` | color | `#181818` | | `--avonni-combobox-action-text-color-disabled` | color | `#dddbda` | | `--avonni-combobox-action-text-color-hover` | color | `#181818` | | `--avonni-combobox-action-text-font-size` | font | `0.75rem` | | `--avonni-combobox-action-text-font-style` | font | `normal` | | `--avonni-combobox-action-text-font-weight` | font | `400` | | `--avonni-combobox-label-text-color` | color | `#3e3e3c` | | `--avonni-combobox-action-icon-color-background` | color | — | | `--avonni-combobox-action-icon-color-foreground` | color | — | | `--avonni-combobox-action-icon-color-background-disabled` | color | — | | `--avonni-combobox-action-icon-color-foreground-disabled` | color | — | | `--avonni-combobox-action-icon-color-background-hover` | color | — | | `--avonni-combobox-action-icon-color-foreground-hover` | color | — | | `--avonni-combobox-action-icon-radius-border` | dimension | `0.25rem` | | `--avonni-combobox-label-font-size` | font | `0.75rem` | | `--avonni-combobox-label-font-style` | font | `normal` | | `--avonni-combobox-label-font-weight` | font | `400` | | `--avonni-combobox-input-color-border` | color | `#747474` | | `--avonni-combobox-input-radius-border` | dimension | `0.25rem` | | `--avonni-combobox-input-styling-border` | string | `solid` | | `--avonni-combobox-input-sizing-border` | dimension | `1px` | | `--avonni-combobox-option-color-background` | color | `transparent` | | `--avonni-combobox-option-color-background-disabled` | color | `transparent` | | `--avonni-combobox-option-color-background-hover` | color | `#f3f2f2` | | `--avonni-combobox-option-label-text-color` | color | `#181818` | | `--avonni-combobox-option-label-text-color-hover` | color | `#181818` | | `--avonni-combobox-option-label-text-color-disabled` | color | `#dddbda` | | `--avonni-combobox-option-label-font-size` | font | `0.75rem` | | `--avonni-combobox-option-label-font-style` | font | `normal` | | `--avonni-combobox-option-label-font-weight` | font | `400` | | `--avonni-combobox-option-secondary-text-color` | color | `#444444` | | `--avonni-combobox-option-secondary-text-color-hover` | color | `#444444` | | `--avonni-combobox-option-secondary-text-color-disabled` | color | `#dddbda` | | `--avonni-combobox-option-secondary-text-font-size` | font | `0.75rem` | | `--avonni-combobox-option-secondary-text-font-style` | font | `normal` | | `--avonni-combobox-option-secondary-text-font-weight` | font | `400` | | `--avonni-combobox-option-avatar-color-border` | color | — | | `--avonni-combobox-option-avatar-radius-border` | dimension | — | | `--avonni-combobox-option-avatar-sizing-border` | sizing | — | | `--avonni-combobox-option-avatar-styling-border` | styling | — | | `--avonni-combobox-option-avatar-initials-text-color` | color | — | | `--avonni-combobox-option-avatar-initials-text-color-hover` | color | — | | `--avonni-combobox-option-avatar-initials-text-font-style` | font | — | | `--avonni-combobox-option-avatar-initials-text-font-weight` | font | — | | `--avonni-combobox-option-avatar-presence-color-border` | color | — | | `--avonni-combobox-option-avatar-presence-radius-border` | dimension | — | | `--avonni-combobox-option-avatar-presence-away-color-background` | color | — | | `--avonni-combobox-option-avatar-presence-blocked-color-background` | color | — | | `--avonni-combobox-option-avatar-presence-busy-color-background` | color | — | | `--avonni-combobox-option-avatar-presence-focus-color-background` | color | — | | `--avonni-combobox-option-avatar-presence-offline-color-background` | color | — | | `--avonni-combobox-option-avatar-presence-online-color-background` | color | — | | `--avonni-combobox-option-avatar-fallback-icon-color-background` | color | — | | `--avonni-combobox-option-avatar-fallback-icon-color-foreground` | color | — | | `--avonni-combobox-option-avatar-fallback-icon-color-background-disabled` | color | `#dddbda` | | `--avonni-combobox-option-avatar-fallback-icon-color-foreground-disabled` | color | — | | `--avonni-combobox-option-avatar-image-object-fit` | string | — | | `--avonni-combobox-pill-color-background` | color | `#ffffff` | | `--avonni-combobox-pill-color-background-hover` | color | `#f3f3f3` | | `--avonni-combobox-pill-text-color` | color | `#181818` | | `--avonni-combobox-pill-text-color-hover` | color | `#181818` | | `--avonni-combobox-pill-color-border` | color | `#747474` | | `--avonni-combobox-pill-color-border-hover` | color | `#747474` | | `--avonni-combobox-pill-sizing-border` | dimension | `1px` | | `--avonni-combobox-pill-styling-border` | styling | `solid` | | `--avonni-combobox-pill-radius-border` | dimension | `0.25rem` | ## Key Considerations * **Single vs multi:** Without `is-multi-select`, `value` is a string; with it, `value` is an array and the `change` detail's `action` reports `select`, `unselect`, or `reorder`. * **Search:** Enable `allow-search` for long lists; combine with `hide-options-until-search` to defer rendering until a query is typed. * **Multi-select limits:** Use `min` and `max` to constrain the number of selected options. * **Nested options:** Options with children emit `levelchange`; provide a `back-action` to navigate back up the hierarchy. * **Accessibility:** Always set `label` so the combobox is announced to assistive technology; use `variant="label-hidden"` if you need to hide it visually. *** ## Troubleshooting Common Issues * **Options not grouping:** Ensure each option's `groups` array references a `name` defined in the `groups` attribute. * **Multi-select value not updating:** Treat `event.detail.value` as an array when `is-multi-select` is present, not a string. * **Search returns nothing:** Confirm `allow-search` is set; customize the empty state with `no-results-message`. * **If issues persist:** Contact our support team at for assistance. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.avonnicomponents.com/lwc-components/core-components/combobox.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.