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 <avonni-combobox> 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.
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.
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
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-error-message
If present, the combobox computes its validity but does not display the error message inline. Use when a parent (e.g. a flow screen) owns the error presentation, to avoid showing the message twice.
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
blur
Remove focus from the combobox.
checkValidity
Check if the input is valid.
close
Close the drop-down.
focus
Set focus on the combobox.
getErrorMessage
Retrieve the current error message. If it is empty, the input is valid.
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.
name
string
The name of the action clicked.
The event properties are as follows.
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.
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.
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.
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.
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.
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.
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 is selected.
The levelchange event returns the following parameters.
value
string
Value of the clicked option.
The event properties are as follows.
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.
option
object
Current parent option, if the visible options are nested.
searchTerm
string
Value of the search input.
The event properties are as follows.
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.
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.
value
string
The value of the scope selected.
The event properties are as follows.
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.
parentValue
string
Value of the parent option, if the search is executed in a nested level.
value
string
Value of the search input.
The event properties are as follows.
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.
actionclick
The event fired when a user clicks on an action.
The actionclick event returns the following parameters.
name
string
The name of the action clicked.
The event properties are as follows.
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.
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.
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.
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.
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.
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.
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.
option
object
Option clicked.
The event properties are as follows.
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.
option
object
Current parent option, if the visible options are nested.
searchTerm
string
Value of the search input.
The event properties are as follows.
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.
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.
value
string
The value of the scope selected.
The event properties are as follows.
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.
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.
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
--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