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.

<aura:component>
    <aura:attribute name="statusOptions" type="List" default="[]"/>
    <aura:handler name="init" value="{! this }" action="{! c.loadOptions }"/>
    <lightning:combobox aura:id="selectItem" name="status" label="Status"
                      placeholder="Choose Status"
                      value="new"
                      onchange="{!c.handleOptionSelected}"
                      options="{!v.statusOptions}"/>
</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.

({
    loadOptions: function (component, event, helper) {
        var options = [
            { value: "new", label: "New" },
            { value: "in-progress", label: "In Progress" },
            { value: "finished", label: "Finished" }
        ];
        component.set("v.statusOptions", options);
    },
    handleChange: function (cmp, event) {
        // Get the string of the "value" attribute on the selected option
        var selectedOptionValue = event.getParam("value");
        alert("Option selected with value: '" + selectedOptionValue + "'");
    }
})

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.

Usage Considerations

Special characters like " must be escaped. For example, you want to display "New".

var options = [
    { value: "\"new\"", label: "\"New\"" },
    { value: "expired", label: "Expired" }
];

When using single quotes in your value, escape the quote with a double slash instead of a single slash.

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.
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 &quot;Select an Option&quot;.
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.