Coral.QuickActions

Current Version: 1.5.0
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-quickactions

QuickActions is an overlay component that reveals actions when interacting with a container.

Preview

 | 
Target
CopyMoveDownloadSharePublish
Markup JavaScript Log
18
<div style="display: inline-block; width:200px; height:90px;padding-top: 60px; text-align: center; border: 1px dashed gray;"id="targetComponent">Target</div>
 
1
<div style="display: inline-block; width:200px; height:90px;padding-top: 60px; text-align: center; border: 1px dashed gray;"id="targetComponent">Target</div>
2
<coral-quickactions placement="top" target="#targetComponent" open>
3
  <coral-quickactions-item icon="copy" type="anchor" href="#">
4
    Copy
5
  </coral-quickactions-item>
6
  <coral-quickactions-item icon="move" type="button" href="">
7
    Move
8
  </coral-quickactions-item>
9
  <coral-quickactions-item icon="download" type="button" href="">
10
    Download
11
  </coral-quickactions-item>
12
  <coral-quickactions-item icon="share" type="button" href="">
13
    Share
14
  </coral-quickactions-item>
15
  <coral-quickactions-item icon="publish" type="button" href="">
16
    Publish
17
  </coral-quickactions-item>
18
</coral-quickactions>

Configuration

Placement
Top Bottom Left Right
Target
Threshold
Interaction
OFF ON

JavaScript Examples

JS Class Initialization

The following JavaScript manually generates a QuickActions component and sets up some properties.
Profession Preferred transport
Witch Broomstick
Alien UFO
Show Markup 
<table class="coral-Table" id="quickActionsTarget">
  <thead>
    <tr class="coral-Table-row">
      <th class="coral-Table-headerCell">Profession</th>
      <th class="coral-Table-headerCell">Preferred transport</th>
    </tr>
  </thead>
  <tbody>
    <tr class="coral-Table-row">
      <td class="coral-Table-cell">Witch</td>
      <td class="coral-Table-cell">Broomstick</td>
    </tr>
    <tr class="coral-Table-row">
      <td class="coral-Table-cell">Alien</td>
      <td class="coral-Table-cell">UFO</td>
    </tr>
  </tbody>
</table>
<script>
  var quickActions = new Coral.QuickActions();
  quickActions.id = 'quickActions';
  quickActions.target = '_prev'; // Let's use the previous element as target
  quickActions.threshold = '2'; // .. and limit the number of Items we show before collapse
  quickActions.placement = 'bottom'; // .. and place at the bottom of the target.
  var target = document.getElementById('quickActionsTarget');
  target.parentNode.insertBefore(quickActions, target.nextSibling); // Add to the DOM
</script>

The QuickActions implement the Collection API as a way of manipulating the action 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.

Manually add Items to the QuickActions

Below we use the Coral.Collection API via the items property to add some actions to the example. 
<script>
  jQuery(function ($) {
    var quickActions = document.querySelector('#quickActions');
    var item1 = {
      icon: 'download',
      content: {
        textContent: 'Download this table'
      },
      type: 'anchor',
      href: '#'
    };
    var item2 = {
      icon: 'copy',
      content: {
        textContent: 'Copy this table'
      }
    };
    var item3 = {
      icon: 'share',
      content: {
        textContent: 'Share this table'
      }
    };
  
    quickActions.items.add(item1);
    quickActions.items.add(item2);
    quickActions.items.add(item3);
  });
</script>

Handling click of an action item

The following shows how to respond to user clicks on a QuickActions item. Click action items in the example and view the log output below. 
<script>
  jQuery(function ($) {
    var console = $('#quickActionsLog');
    var quickActions = document.querySelector('#quickActions');
    quickActions.addEventListener('click', function(event) {
      if (event.target.tagName.toLowerCase() === 'coral-quickactions-item') {
        console.log('item: ' + event.target + ' textContent: ' + event.target.content.textContent);
      }
    });
  });
</script>

Log

Preventing hide on action item click

Use event.preventDefault() in the click event handler to suppress the hide of the QuickActions. Note that if the mouse exits the target, the QuickActions will still hide even if default is prevented. 
<script>
  jQuery(function ($) {
    var quickActions = document.querySelector('#quickActions');
    quickActions.addEventListener('click', function(event) {
      if (event.target.tagName.toLowerCase() === 'coral-quickactions-item') {
        event.preventDefault();
        // QuickActions stay shown.
      }
    });
  });
</script>

User interaction and focus behavior

The interaction property must be 'ON' for user interaction with the target to take effect.

Hovering the target will display the QuickActions. They can also be launched by pressing the shift + F10 key combination when the target is focused. When the QuickActions are shown, the first action button is focused.

When a button in the QuickActions is focused, it is possible to navigate using keys. Navigate right using 'right', 'down' or 'pagedown' keys and left using 'left', 'up' and 'pageup'. A 'home' or 'end' keypress will navigate to the first or last buttons respectively.

An 'escape' key will close the QuickActions, unless the more actions Popover is already open, in which case two presses subsequent will be necessary, the first to close the Popover.

Pressing the 'enter' key for a focused Item will cause a trigger of the click event for that action. Unless the focused item is the more button, in which case the Popover will open.

Coral.QuickActions API

Constructor

JavaScript:

new Coral.QuickActions() or document.createElement('coral-quickactions')

HTML Tag:

<coral-quickactions>

Extends

Sub-components

Static Properties

Coral.QuickActions.interaction {String}

QuickActions interaction values.

Properties:

Name Type Value Description
ON String on Show when the target is hovered or focused and hide when the mouse is moved out or focus is lost.
OFF String off Do not show or hide automatically.

Coral.QuickActions.placement {String}

QuickActions placement values.

Properties:

Name Type Value Description
TOP String top QuickActions inset to the top of the target.
CENTER String center QuickActions inset to the center of the target.
BOTTOM String bottom QuickActions inset to the bottom the target.

Coral.QuickActions.target {String}

QuickActions anchored overlay targets.

Properties:

Name Type Value Description
PARENT String _parent Use the parent element in the DOM.
PREVIOUS String _prev Use the previous sibling element in the DOM.
NEXT String _next Use the next sibling element in the DOM.

Instance Properties

instance.alignAt {Coral.Overlay.align}

The point on the target we should anchor to when positioning.
Default Value:
  • Coral.Overlay.align.CENTER_TOP
HTML Attribute:
  • alignat

instance.alignMy {Coral.Overlay.align}

The point on the QuickActions overlay we should anchor from when positioning.
Default Value:
  • Coral.Overlay.align.CENTER_TOP
HTML Attribute:
  • alignmy

instance.collision {Coral.Overlay.collision}

The collision handling strategy when positioning the overlay relative to a target.
Inherited From:
Default Value:
  • Coral.Overlay.collision.FLIP_FIT
HTML Attribute:
  • collision

instance.focusOnShow {String}

Focus behavior options.

Properties:

Name Type Value Description
ON String on When the overlay is opened, it will be focused.
OFF String off The overlay will not focus itself when opened.
Inherited From:

instance.hidden {Boolean}

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

instance.interaction {Coral.QuickActions.interaction}

Whether the QuickActions should show when the target is interacted with.
Default Value:
  • Coral.QuickActions.interaction.ON
HTML Attribute:
  • interaction

instance.items {Coral.Collection}

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

instance.offset {Number}

The distance the QuickActions should be from the target.
Default Value:
  • 10
HTML Attribute:
  • offset

instance.placement {Coral.Overlay.placement}

The placement of the QuickActions. This property sets Coral.Overlay#alignMy and Coral.Overlay#alignAt. The value may be one of 'top', 'center' and 'bottom' and indicates the vertical alignment of the QuickActions relative to their container.
Default Value:
  • null
HTML Attribute:
  • placement

instance.returnFocus {String}

Return focus options.

Properties:

Name Type Value Description
ON String on When the overlay is closed, the element that was focused before the it was shown will be focused again.
OFF String off Nothing will be focused when the overlay is closed.
Inherited From:

instance.target {Coral.Overlay.target | HTMLElement | String}

The element the overlay should position relative to. It accepts values from Coral.Overlay.target, as well as a DOM element or a CSS selector. If a CSS selector is provided, the first matching element will be used. If a target is not specified, the overlay will not respect Coral.Overlay#alignMy, Coral.Overlay#alignAt, or Coral.Overlay#collision.
Inherited From:
Default Value:
  • null
HTML Attribute:
  • target

instance.threshold {Number}

The number of items that are visible in QuickActions (excluding the show more actions button) before a collapse is enforced. A value <= 0 disables this feature and shows as many items as possible. Regardless of this property, the QuickActions will still fit within their target's width.
Default Value:
  • 4
HTML Attribute:
  • threshold

instance.tracking {Coral.Component.tracking}

Tracking of events. This provides insight on the usage of the components. It accepts "ON" and "OFF". In order to successfully track the events, {Coral.tracking} needs to be configured.
Inherited From:
Default Value:
  • Coral.Component.tracking.ON
HTML Attribute:
  • tracking

instance.trackingElement {String}

The string representing the element name being tracked. This providex additional context to the trackers about the element that was interacted with.
Inherited From:
Default Value:
  • ""
HTML Attribute:
  • trackingelement

instance.trackingFeature {String}

The string representing the feature being tracked. This provides additional context to the analytics trackers about the feature that the element enables.
Inherited From:
Default Value:
  • ""
HTML Attribute:
  • trackingfeature

instance.trapFocus {String}

Focus trap options.

Properties:

Name Type Value Description
ON String on Focus is trapped such that the use cannot focus outside of the overlay.
OFF String off The user can focus outside the overlay as normal.
Inherited From:

instance.within {HTMLElement | String}

The bounding element for the overlay. The overlay will be sized and positioned such that it is contained within this element. It accepts both a DOM Element or a CSS selector. If a CSS selector is provided, the first matching element will be used.
Inherited From:
Default Value:
  • window

Methods

instance._layout

Layout calculation; collapses QuickActions as necessary.

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

Re-position the overlay if it's currently open.
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.QuickActions.Item API

        Constructor

        JavaScript:

        new Coral.QuickActions.Item() or document.createElement('coral-quickactions-item')

        HTML Tag:

        <coral-quickactions-item>

        Extends

        Static Properties

        Coral.QuickActions.Item.type {String}

        Enum for item type values.

        Properties:

        Name Type Value Description
        BUTTON String button Default button type
        ANCHOR String anchor Anchor button type

        Instance Properties

        instance.content {HTMLElement}

        The Item's content zone.

        instance.hidden {Boolean}

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

        instance.href {String}

        Reflected
        When type is Coral.QuickActions.Item.type.ANCHOR, the href will be used for the anchor.
        Default Value:
        • ""
        HTML Attribute:
        • href

        instance.icon {String}

        Reflected
        Specifies the name of the icon to be shown in the QuickActions Item. See Coral.Icon for valid icon names.
        Default Value:
        • ""
        HTML Attribute:
        • icon
        See:

        instance.tracking {Coral.Component.tracking}

        Tracking of events. This provides insight on the usage of the components. It accepts "ON" and "OFF". In order to successfully track the events, {Coral.tracking} needs to be configured.
        Inherited From:
        Default Value:
        • Coral.Component.tracking.ON
        HTML Attribute:
        • tracking

        instance.trackingElement {String}

        The string representing the element name being tracked. This providex additional context to the trackers about the element that was interacted with.
        Inherited From:
        Default Value:
        • ""
        HTML Attribute:
        • trackingelement

        instance.trackingFeature {String}

        The string representing the feature being tracked. This provides additional context to the analytics trackers about the feature that the element enables.
        Inherited From:
        Default Value:
        • ""
        HTML Attribute:
        • trackingfeature

        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.