Coral.StepList

Current Version: 1.2.1
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.
Github: @coralui/coralui-component-steplist

Collection API

The StepList implements the Collection API as a way to manipulate the items. It provides add(), remove(), clear(), and getAll(), as well as their corresponding events to keep track of the items. Check Coral.Collection for more information.

add(item, insertBefore)

The following code adds an item using the JavaScript constructor. After an item is added a coral-collection:add event will be triggered. 

var stepList = new Coral.StepList();
var item = new Coral.Step();
stepList.items.add(item);

Add also allows using an object that represents the item. All values will be set using the multiple value set provided by the Coral.Component class. 

var stepList = new Coral.StepList();
stepList.items.add({
  label: {
    innerHTML: 'Step 1'
  },
  selected: false
});

remove(item)

Item removal is done in a similar fashion. After any removal, the StepList will trigger a coral-collection:remove event. 

stepList.items.remove(item);

Limitations

When very long labels are provided, wrapping will occur and will push the label upwards. This can cause problems if assumptions are made about the height of the StepList, so be wary of this fact if your labels are long.

My text is the longest And my text is quite long If this was in German It would likely look wrong
Show Markup 
<coral-steplist interaction="on">
  <coral-step>My text is the longest</coral-step>
  <coral-step selected>And my text is quite long</coral-step>
  <coral-step>If this was in German</coral-step>
  <coral-step>It would likely look wrong</coral-step>
</coral-steplist>

Coral.StepList API

Constructor

JavaScript:

new Coral.StepList() or document.createElement('coral-steplist')

HTML Tag:

<coral-steplist>

Extends

Mixes In

Static Properties

Coral.StepList.interaction {String}

Enumeration representing StepList interaction patterns.

Properties:

Name Type Value Description
ON String on Steps can be clicked to visit them.
OFF String off Steps cannot be clicked.
To Do:
  • support "click only past steps" mode

Coral.StepList.size {String}

Enumeration representing the StepList size.

Properties:

Name Type Value Description
SMALL String S A small-sized StepList.
LARGE String L A large-sized StepList.

Instance Properties

instance.hidden {Boolean}

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

instance.interaction {Coral.StepList.interaction}

Reflected
Whether Steps should be interactive or not. When interactive, a Step can be clicked to jump to it.
Default Value:
  • Coral.StepList.interaction.OFF
HTML Attribute:
  • interaction

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.selectedItem {HTMLElement}

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

instance.size {Coral.StepList.size}

Reflected
The size of the StepList. It accepts both lower and upper case sizes. Currently only "S" and "L" (the default) are available.
Default Value:
  • Coral.StepList.size.LARGE
HTML Attribute:
  • size

instance.target {HTMLElement | String}

The target component that will be linked to the StepList. It accepts either a CSS selector or a DOM element. If a CSS Selector is provided, the first matching element will be used. Items will be selected based on the index. If both target and Coral.Step#target are set, the second will have higher priority.
Default Value:
  • null
HTML Attribute:
  • target

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.next

Show the next Step.
Fires:
  • Coral.StepList#event:coral-steplist:change

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.previous

Show the previous Step.
Fires:
  • Coral.StepList#event:coral-steplist:change

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.Step API

        Constructor

        JavaScript:

        new Coral.Step() or document.createElement('coral-step')

        HTML Tag:

        <coral-step>

        Extends

        Mixes In

        Sub-components

        Instance Properties

        instance.hidden {Boolean}

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

        instance.label {HTMLElement}

        The Step's label element.

        instance.selected {Boolean}

        Reflected
        Whether the item is selected. When true, the item will appear as the active element in the StepList. The item must be a child of a StepList before this property is set to true.
        Default Value:
        • false
        HTML Attribute:
        • selected

        instance.target {HTMLElement | String}

        The target element that will be selected when this Step is selected. It accepts a CSS selector or a DOM element. If a CSS Selector is provided, the first matching element will be used.
        Default Value:
        • null
        HTML Attribute:
        • target

        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.