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.
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 "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. |