Coral.SelectList

Current Version: 4.0.3
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.Select
Github: @coralui/coralui-component-selectlist

Markup Examples

|

Simple SelectList

Africa America Asia Europe Oceania
Show Markup 
<coral-selectlist>
  <coral-selectlist-item>Africa</coral-selectlist-item>
  <coral-selectlist-item selected>America</coral-selectlist-item>
  <coral-selectlist-item>Asia</coral-selectlist-item>
  <coral-selectlist-item>Europe</coral-selectlist-item>
  <coral-selectlist-item>Oceania</coral-selectlist-item>
</coral-selectlist>

Grouped SelectList

Expression 1 Expression 2 Expression 3 Expression 4 Expression 5
Show Markup 
<coral-selectlist>
  <coral-selectlist-group label="Group 1">
    <coral-selectlist-item>Expression 1</coral-selectlist-item>
    <coral-selectlist-item>Expression 2</coral-selectlist-item>
    <coral-selectlist-item>Expression 3</coral-selectlist-item>
  </coral-selectlist-group>
  <coral-selectlist-group label="Group 2">
    <coral-selectlist-item>Expression 4</coral-selectlist-item>
    <coral-selectlist-item>Expression 5</coral-selectlist-item>
  </coral-selectlist-group>
</coral-selectlist>

SelectList with Icons

Adjust Alert Alert-Add Alias Anchor
Show Markup 
<coral-selectlist>
  <coral-selectlist-item value="adjust">
    <coral-icon icon="adjust"></coral-icon> Adjust
  </coral-selectlist-item>
  <coral-selectlist-item value="alert">
    <coral-icon icon="alert"></coral-icon> Alert
  </coral-selectlist-item>
  <coral-selectlist-item value="alert-add">
    <coral-icon icon="alertAdd"></coral-icon> Alert-Add
  </coral-selectlist-item>
  <coral-selectlist-item value="alias">
    <coral-icon icon="alias"></coral-icon> Alias
  </coral-selectlist-item>
  <coral-selectlist-item value="anchor">
    <coral-icon icon="anchor"></coral-icon> Anchor
  </coral-selectlist-item>
</coral-selectlist>

SelectList with disabled Options

John Lennon George Harrison Paul McCartney Ringo Starr
Show Markup 
<coral-selectlist>
  <coral-selectlist-item value="john">John Lennon</coral-selectlist-item>
  <coral-selectlist-item value="george" disabled>George Harrison</coral-selectlist-item>
  <coral-selectlist-item value="paul">Paul McCartney</coral-selectlist-item>
  <coral-selectlist-item value="ringo">Ringo Starr</coral-selectlist-item>
</coral-selectlist>

SelectList with multiple selection

Africa America Asia Europe Oceania
Show Markup 
<coral-selectlist multiple>
  <coral-selectlist-item>Africa</coral-selectlist-item>
  <coral-selectlist-item>America</coral-selectlist-item>
  <coral-selectlist-item>Asia</coral-selectlist-item>
  <coral-selectlist-item>Europe</coral-selectlist-item>
  <coral-selectlist-item>Oceania</coral-selectlist-item>
</coral-selectlist>

JavaScript Examples

Instantiate with Class

Africa America Asia Europe Oceania
Show Markup 
<coral-selectlist id="mySelectList">
  <coral-selectlist-item value="af">Africa</coral-selectlist-item>
  <coral-selectlist-item value="am" selected="true">America</coral-selectlist-item>
  <coral-selectlist-item value="as">Asia</coral-selectlist-item>
  <coral-selectlist-item value="eu">Europe</coral-selectlist-item>
  <coral-selectlist-item value="oc">Oceania</coral-selectlist-item>
</coral-selectlist>

Getting the selected item

The SelectList provides an attribute to get direct access to the selected item. 

<script>
  function getSelectedItem() {
    var selectlist = document.querySelector('#mySelectList');
    alert('Item label: ' + selectlist.selectedItem.content + ' index: ' + selectlist.items.getAll().indexOf(selectlist.selectedItem));
  }
</script>

Responding to User Interaction

The following shows how to respond to user interaction when an item is selected in the Select component above. 
<script>
  jQuery(function ($) {
    var console = $('#selectlistLog');
    var selectlist = document.querySelector('#mySelectList');
    selectlist.addEventListener('coral-selectlist:change', function(event) {
      console.log('Value (' + event.target.selectedItem.content + ')[' + event.target.selectedItem.value + '] selected.');
    });
  });
</script>

Log

Coral.SelectList API

Constructor

JavaScript:

new Coral.SelectList() or document.createElement('coral-selectlist')

HTML Tag:

<coral-selectlist>

Extends

Mixes In

Sub-components

Instance Properties

instance.groups {Coral.Collection}

Readonly
The Collection Interface that allows interacting with the Coral.SelectList.Group elements that the SelectList contains. This includes items nested inside groups. To manage items contained within a specific group, see Coral.SelectList.Group#items. See Coral.Collection for more details regarding collection APIs.

instance.hidden {Boolean}

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

instance.items {Coral.Collection}

Readonly
The Collection Interface that allows interacting with the items that the component contains. See Coral.Collection for more details.

instance.loading {Boolean}

Reflected
Whether items are being loaded for the SelectList. Toggling this merely shows or hides a loading indicator.
Default Value:
  • false
HTML Attribute:
  • loading

instance.multiple {Boolean}

Whether multiple items can be selected.
Default Value:
  • false
HTML Attribute:
  • multiple

instance.selectedItem {HTMLElement}

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

instance.selectedItems {Array.<HTMLElement>}

Readonly
Returns an Array containing the set selected items.

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-collection:add

Triggered when an item is added to the Collection. Collection events are not synchronous so the DOM may reflect a different reality although every addition or removal will be reported.
Callback Parameters:
Name Type Description
event Object

Event object.

Name Type Description
event.detail.item HTMLElement The item that was added.
Inherited From:

coral-collection:remove

Triggered when an item is removed from a Collection. Collection events are not synchronous so the DOM may reflect a different reality although every addition or removal will be reported.
Callback Parameters:
Name Type Description
event Object

Event object.

Name Type Description
event.detail.item HTMLElement The item that was removed.
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.SelectList.Item API

        Constructor

        JavaScript:

        new Coral.SelectList.Item() or document.createElement('coral-selectlist-item')

        HTML Tag:

        <coral-selectlist-item>

        Extends

        Mixes In

        Instance Properties

        instance.content {HTMLElement}

        Readonly
        The content element for the item.

        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.

              Coral.SelectList.Group API

              Constructor

              JavaScript:

              new Coral.SelectList.Group() or document.createElement('coral-selectlist-group')

              HTML Tag:

              <coral-selectlist-group>

              Extends

              Instance Properties

              instance.hidden {Boolean}

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

              instance.items {Coral.Collection}

              Readonly
              The Collection Interface that allows interacting with the Coral.SelectList.Item elements that the group contains. See Coral.Collection for more details regarding collection APIs.

              instance.label {String}

              Reflected
              The label of the group. It reflects the label attribute to the DOM.
              Default Value:
              • ""
              HTML Attribute:
              • label

              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.