Coral.Select

Current Version: 4.1.7
Note:Any Coral CSS classes and attributes not explicitly mentioned in the public documentation are private and subject to change. Their direct use is not recommended and at high risk of breaking after subsequent updates of CoralUI library. For technical details of how to use Coral safely, please refer to the CoralUI Architecture.
Relevant Specifications: Dropdowns, Confined Filter
Related Components: Coral.Autocomplete, Coral.SelectList
Github: @coralui/coralui-component-select

Select is a form field that allows users to select from a list of options.

Important: If this component is shown on a mobile device, it will show a native select list, instead of the select list styled via CoralUI.

Forms

Vertical Layout

America Europe Africa Asia Oceania
America Europe Africa Asia Oceania
America Europe Africa Asia Oceania
Show Markup 
<form class="coral-Form coral-Form--vertical u-columnMedium">
  <section class="coral-Form-fieldset">
  <div class="coral-Form-fieldwrapper">
    <label id="label-vertical-0" class="coral-Form-fieldlabel">Label</label>
    <coral-select class="coral-Form-field" placeholder="Select one" name="name" labelledby="label-vertical-0">
      <coral-select-item value="am">America</coral-select-item>
      <coral-select-item value="eu">Europe</coral-select-item>
      <coral-select-item value="af">Africa</coral-select-item>
      <coral-select-item value="as">Asia</coral-select-item>
      <coral-select-item value="oc">Oceania</coral-select-item>
    </coral-select>
  </div>
  <div class="coral-Form-fieldwrapper">
    <label id="label-vertical-1" class="coral-Form-fieldlabel">Required</label>
    <coral-select class="coral-Form-field" placeholder="Select one" name="name" labelledby="label-vertical-1" required>
      <coral-select-item value="am">America</coral-select-item>
      <coral-select-item value="eu">Europe</coral-select-item>
      <coral-select-item value="af">Africa</coral-select-item>
      <coral-select-item value="as">Asia</coral-select-item>
      <coral-select-item value="oc">Oceania</coral-select-item>
    </coral-select>
    <coral-icon class="coral-Form-fieldinfo" icon="infoCircle" size="S" id="coral-Form-Vertical-Select-fieldinfo"></coral-icon>
    <coral-tooltip variant="info" placement="right" target="#coral-Form-Vertical-Select-fieldinfo">Required Information</coral-tooltip>
  </div>
  <div class="coral-Form-fieldwrapper">
    <label id="label-vertical-2" class="coral-Form-fieldlabel">Invalid</label>
    <coral-select class="coral-Form-field" placeholder="Select one" name="name" labelledby="label-vertical-2" invalid>
      <coral-select-item value="am">America</coral-select-item>
      <coral-select-item value="eu">Europe</coral-select-item>
      <coral-select-item value="af">Africa</coral-select-item>
      <coral-select-item value="as">Asia</coral-select-item>
      <coral-select-item value="oc">Oceania</coral-select-item>
    </coral-select>
    <coral-icon class="coral-Form-fielderror" icon="infoCircle" size="S" id="coral-Form-Vertical-Select-fielderror"></coral-icon>
    <coral-tooltip variant="error" placement="right" target="#coral-Form-Vertical-Select-fielderror">Error Message</coral-tooltip>
  </div>
  </section>
</form>

Aligned Layout

America Europe Africa Asia Oceania
America Europe Africa Asia Oceania
America Europe Africa Asia Oceania
Show Markup 
<form class="coral-Form coral-Form--aligned u-columnLarge">
  <section class="coral-Form-fieldset">
  <div class="coral-Form-fieldwrapper">
    <label id="label-aligned-0" class="coral-Form-fieldlabel">Label</label>
    <coral-select class="coral-Form-field" placeholder="Select one" name="name" labelledby="label-aligned-0">
      <coral-select-item value="am">America</coral-select-item>
      <coral-select-item value="eu">Europe</coral-select-item>
      <coral-select-item value="af">Africa</coral-select-item>
      <coral-select-item value="as">Asia</coral-select-item>
      <coral-select-item value="oc">Oceania</coral-select-item>
    </coral-select>
  </div>
  <div class="coral-Form-fieldwrapper">
    <label id="label-aligned-1" class="coral-Form-fieldlabel">Required</label>
    <coral-select class="coral-Form-field" placeholder="Select one" name="name" labelledby="label-aligned-1" required>
      <coral-select-item value="am">America</coral-select-item>
      <coral-select-item value="eu">Europe</coral-select-item>
      <coral-select-item value="af">Africa</coral-select-item>
      <coral-select-item value="as">Asia</coral-select-item>
      <coral-select-item value="oc">Oceania</coral-select-item>
    </coral-select>
    <coral-icon class="coral-Form-fieldinfo" icon="infoCircle" size="S" id="coral-Form-Aligned-Select-fieldinfo"></coral-icon>
    <coral-tooltip variant="info" placement="right" target="#coral-Form-Aligned-Select-fieldinfo">Required Information</coral-tooltip>
  </div>
  <div class="coral-Form-fieldwrapper">
    <label id="label-aligned-2" class="coral-Form-fieldlabel">Invalid</label>
    <coral-select class="coral-Form-field" placeholder="Select one" name="name" labelledby="label-aligned-2" invalid>
      <coral-select-item value="am">America</coral-select-item>
      <coral-select-item value="eu">Europe</coral-select-item>
      <coral-select-item value="af">Africa</coral-select-item>
      <coral-select-item value="as">Asia</coral-select-item>
      <coral-select-item value="oc">Oceania</coral-select-item>
    </coral-select>
    <coral-icon class="coral-Form-fielderror" icon="infoCircle" size="S" id="coral-Form-Aligned-Select-fielderror"></coral-icon>
    <coral-tooltip variant="error" placement="right" target="#coral-Form-Aligned-Select-fielderror">Error Message</coral-tooltip>
  </div>
  </section>
</form>

Markup Examples

|

Single Selection with Preselected Item

Actions Add Add-Circle Adjust
Show Markup 
<coral-select name="select11">
  <coral-select-item value="actions"><coral-icon icon="actions"></coral-icon>Actions</coral-select-item>
  <coral-select-item value="add"><coral-icon icon="add"></coral-icon>Add</coral-select-item>
  <coral-select-item value="add-circle"><coral-icon icon="addCircle"></coral-icon>Add-Circle</coral-select-item>
  <coral-select-item value="adjust" selected><coral-icon icon="adjust"></coral-icon>Adjust</coral-select-item>
</coral-select>

Multiple Selection with Preselected Items

Actions Add Add-Circle Adjust
Show Markup 
<coral-select name="select12" multiple>
  <coral-select-item value="actions" selected>Actions</coral-select-item>
  <coral-select-item value="add">Add</coral-select-item>
  <coral-select-item value="add-circle">Add-Circle</coral-select-item>
  <coral-select-item value="adjust" selected>Adjust</coral-select-item>
</coral-select>

Quiet

Actions Add Add-Circle Adjust
Show Markup 
<coral-select name="select13" variant="quiet">
  <coral-select-item value="actions"><coral-icon icon="actions"></coral-icon>Actions</coral-select-item>
  <coral-select-item value="add"><coral-icon icon="add"></coral-icon>Add</coral-select-item>
  <coral-select-item value="add-circle"><coral-icon icon="addCircle"></coral-icon>Add-Circle</coral-select-item>
  <coral-select-item value="adjust" selected><coral-icon icon="adjust"></coral-icon>Adjust</coral-select-item>
</coral-select>

JavaScript Examples

Loading Remote Content

The following shows how to respond to user interaction when an item is selected in the Select component above.
Show Markup 
<coral-select name="select_remote_example" placeholder="Remote content" id="select_remote_example"></coral-select>

The following JavaScript manually adds content to the select component on page initialization

<script>
  $(document).ready(function() {
    var fakeLoadingTimeout;
    var items = [
      {
        value: 'ch',
        content: {
          textContent: 'Chrome'
        }
      },
      {
        value: 'fi',
        content: {
          textContent: 'Firefox'
        }
      },
      {
        value: 'ie',
        content: {
          textContent: 'Internet Explorer'
        }
      },
      {
        value: 'op',
        content: {
          textContent: 'Opera'
        }
      },
      {
        value: 'sa',
        content: {
          textContent: 'Safari'
        }
      }
    ];
  
    var select = $('#select_remote_example').get(0);
    select.addEventListener('coral-select:showitems', function(event) {
      // Stop previous request
      clearTimeout(fakeLoadingTimeout);
    
      // Don't use local selections and show the loading icon
      event.preventDefault();
    
      // Make a request and show suggestions from that
      fakeLoadingTimeout = setTimeout(function() {
        items.forEach(function(value, index) {
          // Add each item
          // This hides the loading indicator automatically
          select.items.add(value);
        });
      }, 1000);
    });
  })
</script>

Coral.Select API

Constructor

JavaScript:

new Coral.Select() or document.createElement('coral-select')

HTML Tag:

<coral-select>

Extends

Sub-components

Static Properties

Coral.Select.variant {String}

Enum for Select variant values.

Properties:

Name Type Value Description
DEFAULT String default A default, gray Select.
QUIET String quiet A Select with no border or background.

Instance Properties

instance.disabled {Boolean}

Reflected
Whether this field is disabled or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • disabled

instance.hidden {Boolean}

Reflected
Whether this component is hidden or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • hidden

instance.invalid {Boolean}

Reflected
Whether the current value of this field is invalid or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • invalid

instance.items {Coral.Collection}

Readonly
The item collection. See Coral.Collection for more details.

instance.labelledBy {String}

Reference to a space delimited set of ids for the HTML elements that provide a label for the formField. Implementers should override this method to ensure that the appropriate descendant elements are labelled using the aria-labelledby attribute. This will ensure that the component is properly identified for accessibility purposes. It reflects the aria-labelledby attribute to the DOM.
Inherited From:
Default Value:
  • null
HTML Attribute:
  • labelledby

instance.loading {Boolean}

Indicates that the Select is currently loading remote data. This will set the wait indicator inside the list.
Default Value:
  • false
HTML Attribute:
  • loading

instance.multiple {Boolean}

Reflected
Indicates whether the select accepts multiple selected values.
Default Value:
  • false
HTML Attribute:
  • multiple

instance.name {String}

Reflected
Name used to submit the data in a form.
Inherited From:
Default Value:
  • ""
HTML Attribute:
  • name

instance.placeholder {String}

Reflected
Contains a hint to the user of what can be selected in the component. If no placeholder is provided, the first option will be displayed in the component.
Default Value:
  • ""
HTML Attribute:
  • placeholder

instance.readOnly {Boolean}

Reflected
Whether this field is readOnly or not. Indicating that the user cannot modify the value of the control. This is ignored for checkbox, radio or fileupload.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • readonly

instance.required {Boolean}

Reflected
Whether this field is required or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • required

instance.selectedItem {HTMLElement}

Readonly
Returns the first selected item in the Select. The value null is returned if no element is selected.

instance.selectedItems {Array.<HTMLElement>}

Readonly
Returns an Array containing the set selected items.

instance.value {String}

This field's current value.
Inherited From:
Default Value:
  • ""
HTML Attribute:
  • value

instance.values {Array.<String>}

The current selected values, as submitted during form submission. When Coral.Select#multiple is false, this will be an array of length 1.

instance.variant {Coral.Select.variant}

The Select's variant.
Default Value:
  • Coral.Select.variant.DEFAULT
HTML Attribute:
  • variant

Methods

instance.get

Get the value of a property.
Parameters:
Name Type Description
property String The name of the property to fetch the value of.
Returns:
Property value. {*}
Inherited From:

instance.hide

Hide this component.
Returns:
this, chainable {Coral.Component}
Inherited From:

instance.off

Remove an event listener.
Parameters:
Name Type Optional Description
eventName String No
 The event name to stop listening for.
selector String Yes
 The selector that was used for event delegation.
func function No
 The function that was passed to on().
useCapture Boolean Yes
 Only remove listeners with useCapture set to the value passed in.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.on

Add an event listener.
Parameters:
Name Type Optional Default Description
eventName String No
 The event name to listen for.
selector String Yes
 The selector to use for event delegation.
func function No
 The function that will be called when the event is triggered.
useCapture Boolean Yes
 Whether or not to listen during the capturing or bubbling phase.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.remove

Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.
Inherited From:

instance.set

Set a single property.
Parameters:
Name Type Description
property String The name of the property to set.
value * The value to set the property to.
silent Boolean If true, events should not be triggered as a result of this set.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.show

Show this component.
Returns:
this, chainable {Coral.Component}
Inherited From:

instance.trigger

Trigger an event.
Parameters:
Name Type Optional Default Description
eventName String No
 The event name to trigger.
props Object Yes
 Additional properties to make available to handlers as event.detail.
bubbles Boolean Yes
 Set to false to prevent the event from bubbling.
cancelable Boolean Yes
 Set to false to prevent the event from being cancelable.
Returns:
CustomEvent object {CustomEvent}
Inherited From:

Events

change

Triggered when the value has changed. This event is only triggered by user interaction.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:

coral-component:attached

Triggered when the component is attached to the DOM.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:
Deprecated:
  • since 1.14.0, use MutationObserver instead.

    coral-component:detached

    Triggered when the component is detached to the DOM.
    Callback Parameters:
    Name Type Description
    event Object Event object.
    Inherited From:
    Deprecated:
    • since 1.14.0, use MutationObserver instead.

      coral-component:ready

      Triggerred when the component has been upgraded and is ready for use.
      Callback Parameters:
      Name Type Description
      event Object Event object.
      Inherited From:
      Deprecated:
      • since 1.9.0, use Coral.commons.ready() instead.

        Coral.Select.Item API

        Constructor

        JavaScript:

        new Coral.Select.Item() or document.createElement('coral-select-item')

        HTML Tag:

        <coral-select-item>

        Extends

        Instance Properties

        instance.content {HTMLElement}

        Item content element.

        instance.disabled {Boolean}

        Reflected
        Whether this item is disabled. When set to true, this will prevent every user interaction with the item. If disabled is set to true for a selected item it will be deselected.
        Default Value:
        • false
        HTML Attribute:
        • disabled

        instance.hidden {Boolean}

        Reflected
        Whether this component is hidden or not.
        Inherited From:
        Default Value:
        • false
        HTML Attribute:
        • hidden

        instance.selected {Boolean}

        Reflected
        Whether the item is selected. Selected cannot be set to true if the item is disabled.
        Default Value:
        • false
        HTML Attribute:
        • selected

        instance.value {String}

        Reflected
        Value of the item. If not explicitly set, the value of Node.textContent is returned.
        Default Value:
        • ""
        HTML Attribute:
        • value

        Methods

        instance.get

        Get the value of a property.
        Parameters:
        Name Type Description
        property String The name of the property to fetch the value of.
        Returns:
        Property value. {*}
        Inherited From:

        instance.hide

        Hide this component.
        Returns:
        this, chainable {Coral.Component}
        Inherited From:

        instance.off

        Remove an event listener.
        Parameters:
        Name Type Optional Description
        eventName String No
        		 The event name to stop listening for.
        selector String Yes
        		 The selector that was used for event delegation.
        func function No
        		 The function that was passed to on().
        useCapture Boolean Yes
        		 Only remove listeners with useCapture set to the value passed in.
        Returns:
        this, chainable. {Coral.Component}
        Inherited From:

        instance.on

        Add an event listener.
        Parameters:
        Name Type Optional Default Description
        eventName String No
        		 The event name to listen for.
        selector String Yes
        		 The selector to use for event delegation.
        func function No
        		 The function that will be called when the event is triggered.
        useCapture Boolean Yes
        		 Whether or not to listen during the capturing or bubbling phase.
        Returns:
        this, chainable. {Coral.Component}
        Inherited From:

        instance.remove

        Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.
        Inherited From:

        instance.set

        Set a single property.
        Parameters:
        Name Type Description
        property String The name of the property to set.
        value * The value to set the property to.
        silent Boolean If true, events should not be triggered as a result of this set.
        Returns:
        this, chainable. {Coral.Component}
        Inherited From:

        instance.show

        Show this component.
        Returns:
        this, chainable {Coral.Component}
        Inherited From:

        instance.trigger

        Trigger an event.
        Parameters:
        Name Type Optional Default Description
        eventName String No
        		 The event name to trigger.
        props Object Yes
        		 Additional properties to make available to handlers as event.detail.
        bubbles Boolean Yes
        		 Set to false to prevent the event from bubbling.
        cancelable Boolean Yes
        		 Set to false to prevent the event from being cancelable.
        Returns:
        CustomEvent object {CustomEvent}
        Inherited From:

        Events

        coral-component:attached

        Triggered when the component is attached to the DOM.
        Callback Parameters:
        Name Type Description
        event Object Event object.
        Inherited From:
        Deprecated:
        • since 1.14.0, use MutationObserver instead.

          coral-component:detached

          Triggered when the component is detached to the DOM.
          Callback Parameters:
          Name Type Description
          event Object Event object.
          Inherited From:
          Deprecated:
          • since 1.14.0, use MutationObserver instead.

            coral-component:ready

            Triggerred when the component has been upgraded and is ready for use.
            Callback Parameters:
            Name Type Description
            event Object Event object.
            Inherited From:
            Deprecated:
            • since 1.9.0, use Coral.commons.ready() instead.