Single select

Ask a question Design guidelines

Description

Renders a type-ahead where the user can select only one option. The suggestions will match what the user types in the input field.

Summary

API status:	experimental
Included in AUI core?	Not in core You must explicitly require the web resource key.
Web resource key:	`com.atlassian.auiplugin:aui-select`
Experimental since:	5.8.0

Examples

Single Select is a purely markup initialised component, these code samples correspond to the examples above.

Synchronous (HTML)

<form class="aui">
    <label for="sync-product-single-select">Choose your product synchronously:</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)

<form class="aui">
    <label for="async-product-single-select">Choose your product asynchronously (you need to type to initiate a search):</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>

Initialization

There is no need to call any javascript to initialize an aui select component, you simply need to add the <aui-select> element with your desired options on the page.

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-value	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

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.

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.

Events

Event name	Description
change	is triggered after the single select value is modified either by selection or by setting the value through javascript.