Single selects
Summary
Renders a type-ahead where the user can select only one option. The suggestions will match what the user types in the input field.
Status
| API status: | general |
|---|---|
| Web resource key: |
com.atlassian.auiplugin:aui-select
|
| AMD Module key: |
require('aui/select')
|
| Experimental API: | 5.8 |
| General API: | 6 |
Examples
Single Select is a purely markup initialised component, these code samples correspond to the examples above.
Synchronous (HTML)
Asynchronous (HTML)
HTML API
aui-select
These options are passed in as attributes on the| Attribute | Description |
|---|---|
| id |
The id to be placed on the input element of the select this id is removed from the aui-select element after initialization This id is used for accessibility purposes; behavior/styling should not be bound to it as this could change in the future. |
| name | The name attribute that is to be put on the input element |
| placeholder | The placeholder value that the input should use. |
| src |
The URL that is to be used for an async single-select. The expected response format from the server is a JSON array of objects with label and value properties: The URL should return the full set of results that requires client-side filtering. Notes for server implementationsFor large datasets it might be necessary to do some server-side filtering as well. The AUI single select makes a request with a In this example the |
| no-empty-values | A boolean attribute specifying that empty values are not allowed for this field. |
| can-create-values | A boolean attribute that allows a user of the <aui-select> to select any value, rather than just those in the option list or remote source. |
aui-option
The options placed inside the select also have some attribute options. To set the display value of the option simply set the text node within the aui-option element.
| Attribute | Description |
|---|---|
| value | The value of the option used by the select to determine the value of the input field when it is selected |
| img-src | A url to an image, can be a relative URL. Given URL is escaped on render with use of encodeURI. This may affect your application in situations such as when given URL contains additional attributes or special characters. |
| selected | A boolean attribute, whether the current option is the selected one. Implicitly controls the value attribute of the containing |
JavaScript API
aui-select
These javascript methods and properties for the aui-select are found on the parent element of the select.
To find them simply use native DOM methods:
| Method/Property | Description |
|---|---|
| value | Can be used to get and set the current selected value of the select. |
| Event name | Description |
|---|---|
| change | is triggered after the single select value is modified either by selection or by setting the value through javascript. |
aui-option
These javascript methods and properties for the aui-option are found on the option element itself.
To find them simply use native DOM methods:
| Method/Property | Description |
|---|---|
| value | Can be used to get and set the associated value of the option. |
| serialize | Turns the value, label and image properties of the aui-option into a JSON object. |
A11Y guidelines
Side note: whether you'd follow these guidelines or not, it's always advised to at least test your markup with a screen reader software.
aui-label element
Use an aui-select component with an aui-label which is connected to aui-select via attribute for="aui-select-id".
The label is used for Assistive Technologies to describe the purpose of the control.
aria-label attribute
It is not recommended to omit the aui-label element.
However, if you do not have any visible labels you always can provide description via
aria-label attribute.
Recommendation
Please use the Web Accessibility Initiative (WAI) patterns as a reference for implementing accessible components.