Coral.Overlay

Current Version: 1.2.5
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-overlay

Example

Change the menus to see how the overlay positions itself.

Hello!

Coral.Overlay API

Constructor

JavaScript:

new Coral.Overlay() or document.createElement('coral-overlay')

HTML Tag:

<coral-overlay>

Extends

Mixes In

Static Properties

Coral.Overlay.align {Object}

Valid alignment pairs.

Properties:

Name Type Value Description
LEFT_TOP Object left top Use the top of the left side as an anchor point.
LEFT_CENTER Object left center Use the center of the left side as an anchor point.
LEFT_BOTTOM Object left bottom Use the bottom of the left side as an anchor point.
CENTER_TOP Object center top Use the center of the top side as an anchor point.
CENTER_CENTER Object center center Use the center as an anchor point.
CENTER_BOTTOM Object center bottom Use the center of the bottom side as an anchor point.
RIGHT_TOP Object right top Use the top of the right side as an anchor point.
RIGHT_CENTER Object right center Use the center of the right side as an anchor point.
RIGHT_BOTTOM Object right bottom Use the bottom of the right side as an anchor point.

Coral.Overlay.collision {String}

Collision detection strategies.

Properties:

Name Type Value Description
FLIP String flip Flips the element to the opposite side of the target and the collision detection is run again to see if it will fit. Whichever side allows more of the element to be visible will be used.
FIT String fit Shift the element away from the edge of the window.
FLIP_FIT String flipfit First applies the flip logic, placing the element on whichever side allows more of the element to be visible. Then the fit logic is applied to ensure as much of the element is visible as possible.
NONE String none Does not apply any collision detection.

Coral.Overlay.interaction {String}

Boolean enumeration for interaction values.

Properties:

Name Type Value Description
ON String on Keyboard interaction is enabled.
OFF String off Keyboard interaction is disabled.

Coral.Overlay.placement {Object}

Overlay placement values.

Properties:

Name Type Value Description
LEFT Object left An overlay anchored to the left of the target.
RIGHT Object right An overlay anchored to the right of the target.
BOTTOM Object bottom An overlay anchored at the bottom the target.
TOP Object top An overlay anchored at the top target.

Coral.Overlay.target {String}

Anchored overlay targets.

Properties:

Name Type Value Description
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_CENTER
HTML Attribute:
  • alignat

instance.alignMy {Coral.Overlay.align}

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

instance.collision {Coral.Overlay.collision}

The collision handling strategy when positioning the overlay relative to a target.
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.

instance.focusOnShow {Coral.mixin.overlay.focusOnShow | HTMLElement | String}

Whether to focus the overlay, when opened or not. By default the overlay itself will get the focus. It also accepts an instance of HTMLElement or a selector like ':first-child' or 'button:last-of-type'. If the selector returns multiple elements, it will focus the first element inside the overlay that matches the selector.
Default Value:
HTML Attribute:
  • focusonshow

instance.hidden {Boolean}

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

instance.interaction {Coral.Overlay.interaction}

Whether keyboard interaction is enabled.
Default Value:
  • Coral.Overlay.interaction.ON

instance.offset {Number}

The distance the overlay should be from its target.
Default Value:
  • 0
HTML Attribute:
  • offset

instance.open {Boolean}

Reflected
Whether this overlay is open or not.
Default Value:
  • false
HTML Attribute:
  • open

instance.placement {Coral.Overlay.placement}

The placement of the overlay. This property sets Coral.Overlay#alignMy and Coral.Overlay#alignAt.
Default Value:
  • null
HTML Attribute:
  • placement

instance.returnFocus {Coral.mixin.overlay.returnFocus}

Whether to return focus to the previously focused element when closed.
Default Value:
  • Coral.mixin.overlay.returnFocus.OFF
HTML Attribute:
  • returnfocus

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.

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.
Default Value:
  • null
HTML Attribute:
  • target

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.

instance.trapFocus {Coral.mixin.overlay.trapFocus}

Whether to trap tabs and keep them within the overlay.
Default Value:
  • Coral.mixin.overlay.trapFocus.OFF
HTML Attribute:
  • 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.
Default Value:
  • window

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

Close the overlay.
Returns:
this, chainable {Coral.Component}

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.

instance.returnFocusTo

Set the element that focus should be returned to when the overlay is hidden.
Parameters:
Name Type Description
element HTMLElement The element to return focus to. This must be a DOM element, not a jQuery object or selector.
Returns:
this, chainable {Coral.Component}

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

Open the overlay and set the z-index accordingly.
Returns:
this, chainable {Coral.Component}

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-overlay:beforeclose

Triggerred before the component is closed with hide() or instance.open = false.
Callback Parameters:
Name Type Description
event Object

Event object.

Name Type Description
event.preventDefault function Call to stop the overlay from closing.

coral-overlay:beforeopen

Triggerred before the component is opened with show() or instance.open = true.
Callback Parameters:
Name Type Description
event Object

Event object.

Name Type Description
event.preventDefault function Call to stop the overlay from opening.

coral-overlay:close

Triggerred after the component is closed with hide() or instance.open = false
Callback Parameters:
Name Type Description
event Object Event object.

coral-overlay:open

Triggerred after the overlay is opened with show() or instance.open = true
Callback Parameters:
Name Type Description
event Object Event object.

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