Current Version: 1.4.6

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.

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

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.

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.

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.

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

Coral.QuickActions.Item

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:

Coral.Overlay#collision

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:

Coral.Overlay#focusOnShow

instance.hidden {Boolean} Reflected

Whether this component is hidden or not.

Inherited From:

Coral.Component#hidden

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:

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:

Coral.Overlay#returnFocus

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:

Coral.Overlay#target

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:

HTML Attribute:

threshold

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:

Coral.Overlay#trapFocus

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:

Coral.Overlay#within

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:

Coral.Component#get

instance.hide

Hide this component.

Returns:: this, chainable {Coral.Component}

Inherited From:

Coral.Component#hide

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:

Coral.Component#off

instance.on

Add an event listener.

Parameters:

Name	Type	Optional	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:

Coral.Component#on

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:

Coral.Component#remove

instance.reposition

Re-position the overlay if it's currently open.

Inherited From:

Coral.Overlay#reposition

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:

Coral.Component#set

instance.show

Show this component.

Returns:: this, chainable {Coral.Component}

Inherited From:

Coral.Component#show

instance.trigger

Trigger an event.

Parameters:

Name	Type	Optional	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:

Coral.Component#trigger

Events

coral-component:attached

Triggered when the component is attached to the DOM.

Callback Parameters:

Name	Type	Description
event	Object	Event object.

Inherited From:

Coral.Component#coral-component:attached

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:

Coral.Component#coral-component:detached

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:

Coral.Component#coral-component:ready

Deprecated:

since 1.9.0, use Coral.commons.ready() instead.

coral-overlay:positioned

Triggered after the overlay is positioned.

Callback Parameters:

Name Type Description

event

Object

Event object.

Name	Type	Description
event.detail.vertical	String	The vertical position of the target relative to the overlay. `top` when the overlay is at the bottom, `bottom` when it is at the top.
event.detail.horizontal	String	The horizontal position of the target relative to the overlay. `left` when the overlay is to the right, `right` when it is to the left.
event.detail.target	String	The target's position.
event.detail.element	String	The overlay's position.

Inherited From:

Coral.Overlay#coral-overlay:positioned

Coral .QuickActions.Item API

Constructor

JavaScript:: new Coral.QuickActions.Item() or document.createElement('coral-quickactions-item')
HTML Tag:: <coral-quickactions-item>

Extends

Coral.Component

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:

Coral.Component#hidden

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:

Coral.Icon

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:

Coral.Component#get

instance.hide

Hide this component.

Returns:: this, chainable {Coral.Component}

Inherited From:

Coral.Component#hide

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:

Coral.Component#off

instance.on

Add an event listener.

Parameters:

Name	Type	Optional	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:

Coral.Component#on

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:

Coral.Component#remove

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:

Coral.Component#set

instance.show

Show this component.

Returns:: this, chainable {Coral.Component}

Inherited From:

Coral.Component#show

instance.trigger

Trigger an event.

Parameters:

Name	Type	Optional	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:

Coral.Component#trigger

Events

coral-component:attached

Triggered when the component is attached to the DOM.

Callback Parameters:

Name	Type	Description
event	Object	Event object.

Inherited From:

Coral.Component#coral-component:attached

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:

Coral.Component#coral-component:detached

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:

Coral.Component#coral-component:ready

Deprecated:

since 1.9.0, use Coral.commons.ready() instead.

Coral.QuickActions

Coral.QuickActions API

JavaScript:

HTML Tag:

Coral.QuickActions.interaction {String}

Properties:

Coral.QuickActions.placement {String}

Properties:

Coral.QuickActions.target {String}

Properties:

instance.alignAt {Coral.Overlay.align}

instance.alignMy {Coral.Overlay.align}

instance.collision {Coral.Overlay.collision}

instance.focusOnShow {String}

Properties:

instance.hidden {Boolean}

instance.interaction {Coral.QuickActions.interaction}

instance.items {Coral.Collection}

instance.offset {Number}

instance.placement {Coral.Overlay.placement}

instance.returnFocus {String}

Properties:

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

instance.threshold {Number}

instance.trapFocus {String}

Properties:

instance.within {HTMLElement | String}

Event object.

Coral.QuickActions.Item API

JavaScript:

HTML Tag:

Coral.QuickActions.Item.type {String}

Properties:

instance.content {HTMLElement}

instance.hidden {Boolean}

instance.href {String}

instance.icon {String}

Coral .QuickActions.Item API