Single selects

Ask a question

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)

HipChatJIRAConfluenceStashFeCru

Demo code
AخA
 
<form class="aui">
    <aui-label for="sync-product-single-select">Choose your product synchronously:</aui-label>
    <p>
        <aui-select
            id="sync-product-single-select"
            name="product"
            placeholder="Select a product"
        >
            <aui-option>HipChat</aui-option>
            <aui-option>JIRA</aui-option>
            <aui-option>Confluence</aui-option>
            <aui-option>Stash</aui-option>
            <aui-option>FeCru</aui-option>
        </aui-select>
    </p>
</form>

Asynchronous (HTML)

Demo code
 
<form class="aui">
    <aui-label for="async-product-single-select">Choose your product asynchronously (you need to type to initiate a search):</aui-label>
    <p>
        <aui-select
            id="async-product-single-select"
            name="product"
            placeholder="Select a product"
            src="products"
            value="type to trigger async"
        ></aui-select>
    </p>
</form>

HTML API

aui-select

These options are passed in as attributes on the <aui-select> element.
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:

 
[
  {"label": "First Value"},
  {"label": "Second Value"},
  {"label": "Third Value", "value": "third-value"},
  {"label": "Fourth Value", "value": "fourth-value", "img-src": "url/avatar.png"}
]

The URL should return the full set of results that requires client-side filtering.

Notes for server implementations

For large datasets it might be necessary to do some server-side filtering as well. The AUI single select makes a request with a q query parameter which is taken from the value of the input field; if you wish to filter server-side you simply need to accept this parameter and do filtering based on its value. The parameter used is not configurable. Sample URL:

 
http://my-server.com/searchResults?q=$valueFromInput

In this example the src attribute would be set to http://my-server.com/searchResults or /searchResults
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 <aui-select>. First <aui-option> with the attribute wins.

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:

 
document.getElementById("my-aui-select-element");
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:

 
document.querySelector('#my-aui-select aui-option[value="my-value"]');
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.