lightning:combobox

A widget that provides an input field that is readonly, accompanied with a dropdown list of selectable options.

lightning:combobox is an input element that enables single selection from a list of options. The result of the selection is displayed as the value of the input.

This component inherits styling from combobox in the Lightning Design System.

This example creates a list of options during init with a default selection.

1<aura:component>
2    <aura:attribute name="statusOptions" type="List" default="[]"/>
3    <aura:handler name="init" value="{! this }" action="{! c.loadOptions }"/>
4    <lightning:combobox aura:id="selectItem" name="status" label="Status"
5                      placeholder="Choose Status"
6                      value="new"
7                      onchange="{!c.handleOptionSelected}"
8                      options="{!v.statusOptions}"/>
9</aura:component>

In your client-side controller, define an array of options and assign it to the statusOptions attribute. Each option corresponds to a list item on the dropdown list.

1({
2    loadOptions: function (component, event, helper) {
3        var options = [
4            { value: "new", label: "New" },
5            { value: "in-progress", label: "In Progress" },
6            { value: "finished", label: "Finished" }
7        ];
8        component.set("v.statusOptions", options);
9    },
10    handleChange: function (cmp, event) {
11        // Get the string of the "value" attribute on the selected option
12        var selectedOptionValue = event.getParam("value");
13        alert("Option selected with value: '" + selectedOptionValue + "'");
14    }
15})

Selecting an option triggers the onchange event, which calls the handleChange client-side controller. To check which option has been clicked, use event.getParam("value"). Calling cmp.find("mycombobox").get("v.value"); returns the currently selected option.

Input Validation

Client-side input validation is available for this component. You can make the the selection required by setting required="true". An error message is automatically displayed when an item is not selected and required="true".

To check the validity states of an input, use the validity attribute, which is based on the ValidityState object. You can access the validity states in your client-side controller. This validity attribute returns an object with boolean properties. See lightning:input for more information.

You can override the default message by providing your own value for messageWhenValueMissing.

Accessibility

You must provide a text label for accessibility to make the information available to assistive technology. The label attribute creates an HTML label element for your input component. To hide a label from view and make it available to assistive technology, use the label-hidden variant.

Methods

This component supports the following methods.

focus(): Sets focus on the element.

checkValidity(): Returns the valid property value (Boolean) on the ValidityState object to indicate whether the combobox has any validity errors.

setCustomValidity(message): Sets a custom error message to be displayed when the combobox value is submitted.

message (String): The string that describes the error. If message is an empty string, the error message is reset.

Attributes

Attribute Name	Attribute type	Description	Required?
`body`	Component[]	The body of the component. In markup, this is everything in the body of the tag.
`name`	String	Specifies the name of an input element.	Yes
`value`	Object	Specifies the value of an input element.
`variant`	String	The variant changes the appearance of an input field. Accepted variants include standard and label-hidden. This value defaults to standard.
`disabled`	Boolean	Specifies that an input element should be disabled. This value defaults to false.
`readonly`	Boolean	Specifies that an input field is read-only. This value defaults to false.
`required`	Boolean	Specifies that an input field must be filled out before submitting the form. This value defaults to false.
`validity`	Object	Represents the validity states that an element can be in, with respect to constraint validation.
`onchange`	Action	The action triggered when a value attribute changes.
`accesskey`	String	Specifies a shortcut key to activate or focus an element.
`tabindex`	Integer	Specifies the tab order of an element (when the tab button is used for navigating).
`onfocus`	Action	The action triggered when the element receives focus.
`onblur`	Action	The action triggered when the element releases focus.
`class`	String	A CSS class for the outer element, in addition to the component's base classes.
`title`	String	Displays tooltip text when the mouse moves over the element.
`options`	Object[]	A list of options that are available for selection. Each option has the following attributes: class, selected, label, and value.	Yes
`label`	String	Text label for the combobox.	Yes
`placeholder`	String	Text that is displayed before an option is selected, to prompt the user to select an option. The default is "Select an Option".
`dropdownAlignment`	String	Determines the alignment of the drop-down relative to the input. Available values are left, center, right, bottom-left, bottom-center, bottom-right. The default is left.
`messageWhenValueMissing`	String	Error message to be displayed when the value is missing and input is required.

Lightning Components Developer Guide

lightning:combobox

Attributes