Constructor
JavaScript:
-
new Coral.Overlay()
ordocument.createElement('coral-overlay')
HTML Tag:
-
<coral-overlay>
Extends
Mixes In
Static Properties
-
Coral.Overlay.align {Object}
-
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}
-
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}
-
Properties:
Name Type Value Description ON String on Keyboard interaction is enabled. OFF String off Keyboard interaction is disabled. -
Coral.Overlay.placement {Object}
-
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}
-
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.
Valid alignment pairs.
Collision detection strategies.
Boolean enumeration for interaction values.
Overlay placement values.
Anchored overlay targets.
Instance Properties
-
instance.alignAt {Coral.Overlay.align}
-
- Default Value:
- Coral.Overlay.align.CENTER_CENTER
- HTML Attribute:
- alignat
-
instance.alignMy {Coral.Overlay.align}
-
- Default Value:
- Coral.Overlay.align.CENTER_CENTER
- HTML Attribute:
- alignmy
-
instance.collision {Coral.Overlay.collision}
-
- Default Value:
- Coral.Overlay.collision.FLIP_FIT
- HTML Attribute:
- collision
-
instance.focusOnShow {String}
-
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}
-
- Default Value:
- HTML Attribute:
- focusonshow
-
instance.hidden {Boolean}
Reflected -
- Inherited From:
- Default Value:
- false
- HTML Attribute:
- hidden
-
instance.interaction {Coral.Overlay.interaction}
-
- Default Value:
- Coral.Overlay.interaction.ON
-
instance.offset {Number}
-
- Default Value:
- 0
- HTML Attribute:
- offset
-
instance.open {Boolean}
Reflected -
- Default Value:
- false
- HTML Attribute:
- open
-
instance.placement {Coral.Overlay.placement}
-
- Default Value:
- null
- HTML Attribute:
- placement
-
instance.returnFocus {Coral.mixin.overlay.returnFocus}
-
- Default Value:
- Coral.mixin.overlay.returnFocus.OFF
- HTML Attribute:
- returnfocus
-
instance.returnFocus {String}
-
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}
-
- Default Value:
- null
- HTML Attribute:
- target
-
instance.trapFocus {String}
-
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}
-
- Default Value:
- Coral.mixin.overlay.trapFocus.OFF
- HTML Attribute:
- trapfocus
-
instance.within {HTMLElement | String}
-
- Default Value:
- window
The point on the target we should anchor to when positioning.
The point on the overlay we should anchor from when positioning.
The collision handling strategy when positioning the overlay relative to a target.
Focus behavior options.
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.
Whether this component is hidden or not.
Whether keyboard interaction is enabled.
The distance the overlay should be from its target.
Whether this overlay is open or not.
The placement of the overlay. This property sets Coral.Overlay#alignMy and Coral.Overlay#alignAt.
Whether to return focus to the previously focused element when closed.
Return focus options.
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.
Focus trap options.
Whether to trap tabs and keep them within the overlay.
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.
Methods
-
instance.get
-
- Parameters:
-
Name Type Description property String The name of the property to fetch the value of. - Returns:
-
Property value. {*}
- Inherited From:
-
instance.hide
-
- Returns:
-
this, chainable {Coral.Component}
-
instance.hide
-
- Returns:
-
this, chainable {Coral.Component}
- Inherited From:
-
instance.off
-
- 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
-
- 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
-
- Inherited From:
-
instance.reposition
-
-
instance.returnFocusTo
-
- 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
-
- 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
-
- Returns:
-
this, chainable {Coral.Component}
- Inherited From:
-
instance.show
-
- Returns:
-
this, chainable {Coral.Component}
-
instance.trigger
-
- 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:
Get the value of a property.
Close the overlay.
Hide this component.
Remove an event listener.
Add an event listener.
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.
Re-position the overlay if it's currently open.
Set the element that focus should be returned to when the overlay is hidden.
Set a single property.
Show this component.
Open the overlay and set the z-index accordingly.
Trigger an event.
Events
-
coral-overlay:beforeclose
-
- 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
-
- 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
-
- Callback Parameters:
-
Name Type Description event Object Event object.
-
coral-overlay:open
-
- Callback Parameters:
-
Name Type Description event Object Event object.
-
coral-component:attached
-
- Callback Parameters:
-
Name Type Description event Object Event object.
- Inherited From:
- Deprecated:
- since 1.14.0, use
MutationObserver
instead.
- since 1.14.0, use
-
coral-component:detached
-
- Callback Parameters:
-
Name Type Description event Object Event object.
- Inherited From:
- Deprecated:
- since 1.14.0, use
MutationObserver
instead.
- since 1.14.0, use
-
coral-component:ready
-
- Callback Parameters:
-
Name Type Description event Object Event object.
- Inherited From:
- Deprecated:
- since 1.9.0, use
Coral.commons.ready()
instead.
- since 1.9.0, use
-
coral-overlay: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.
Triggerred before the component is closed with
hide()
or instance.open = false
.
Triggerred before the component is opened with
show()
or instance.open = true
.
Triggerred after the component is closed with
hide()
or instance.open = false
Triggerred after the overlay is opened with
show()
or instance.open = true
Triggered when the component is attached to the DOM.
Triggered when the component is detached to the DOM.
Triggerred when the component has been upgraded and is ready for use.
Triggered after the overlay is positioned.