@financial-times/o-overlay

o-overlay

Configurable custom overlay box that can be used to show overlay windows. The overlays can also be switched to display differently on small screens.

• Usage
• Markup
• Sass
• JavaScript
  • Declarative
  • Imperative
  • Option reference
  • API Overview
• Events
• Troubleshooting
• Migration Guide
• Contact
• Licence

Usage

Check out how to include Origami components in your project to get started with o-overlay.

Markup

A new overlay may be created imperatively with JavaScript, without any markup. Alternatively, define an overlay declaratively by adding a template of overlay content and a button to open the overlay.

To define a template add the following script tag with the content of your overlay. Ensure you specify a unique id for your template:

<script type="text/template" id="overlay1-content">
	<p>Content of overlay</p>
</script>

Then add a trigger button with the class o-overlay-trigger, which will open the overlay on click. Connect the trigger to your overlay by specifying the template id in data-o-overlay-src with a # (in the format of an id selector). Then name your overlay with a unique id using the data-o-overlay-id attribute.

<button
	class="o-overlay-trigger"
	data-o-overlay-src="#overlay1-content"
	data-o-overlay-id="overlay1"
>
	Open!
</button>

Configure overlay options by adding them as data attributes to the trigger element, data-o-overlay-[OPTION]. For instance add data-o-overlay-compact="true" for a compact overlay:

<button
	class="o-overlay-trigger"
	data-o-overlay-src="#overlay1-content"
	data-o-overlay-id="overlay1"
	data-o-overlay-compact="true"
>
	Open!
</button>

Sass

Include the oOverlay mixin to output style for all o-overlay features:

@include oOverlay();

.o-overlay {
	/* styles */
}
.o-overlay--compact {
	/* styles */
}
.o-overlay--full-screen {
	/* styles */
}
/* etc. */

To specify specific variants to output styles for pass options (see variants for available options).

For example, to output only the base styles and the compact variant, ignoring other variants:

@include oOverlay(
	$opts: (
		'variants': (
			'compact',
		),
	)
);

.o-overlay {
	/* styles */
}
.o-overlay--compact {
	/* styles */
}

Variants

This table outlines all of the possible variants you can request in the oOverlay mixin:

Size	Notes	Brand support
compact	Included by default	core, internal, whitelabel
full-screen	Included by default	core, internal, whitelabel
header-shaded	Included by default	core, internal, whitelabel

JavaScript

Declarative

JavaScript is initialised on o-overlay elements automatically for Origami Build Service users. If your project is using a manual build process, initialise o-overlay manually.

For example call the init method to initialise all o-overlay instances in the document:

import oOverlay from 'o-overlay';
oOverlay.init();

Or pass an element to initialise a specific o-overlay instance:

import oOverlay from 'o-overlay';
const oOverlayElement = document.getElementById('#my-o-overlay-element');
oOverlay.init(oOverlayElement);

Imperative

You may also construct a new overlay without existing o-overlay elements. The constructor accepts two arguments:

• id: Unique identifier string for the overlay within the page
• options: JSON object that configures the overlay

var myOverlay = new Overlay('myOverlay', {
	html: 'Hello world',
	trigger: '.blah',
});

Option reference

• heading: Object. Options for the Overlay header
  • .title: String. Your overlay's title
  • .visuallyhidetitle: Boolean. If you want to provide a different title style, this option will prevent the title span from being added to the overlay. (In this case the title is only used for aria labelling) Default: false.
  • .shaded: Boolean. Whether to shade the background of the header. Note: for this to work properly, the heading-shaded variant must be included with the CSS (it is by default)
• modal: Boolean. Whether the overlay should have modal behaviour or not. This will add a translucent shadow between the page and the overlay. Modal overlays also disable scroll on the underlying document. Default: true.
• fullscreen: Boolean. If set to true, the overlay will display full screen. This overlay disables scroll on the underlying document and is dismissible with the back button. Note: for this to work properly, the full-screen variant must be included with the CSS (it is by default)
• compact: Boolean. If true, the .o-overlay--compact class will be added to the overlay that reduces heading font-size and paddings in the content. Note: for this to work properly, the compact variant must be included with the CSS (it is by default)
• src: String. Either a url from which HTML to populate the overlay can be loaded, or a querySelector string identifying an element from which the textContent should be extracted.
• html: String or HTMLElement. Raw HTML (cannot be set declaratively)
• class: String. The custom classes to apply to to the overlay e.g. o-overlay--my-modifier.
• trigger: String or HTMLElement. querySelector expression or HTMLElement. When there's a trigger set, a click event handler will be added to it that will open or close the overlay accordingly. (cannot be set declaratively)
• zindex: String. Value of the CSS z-index property of the overlay. Default set via CSS: '10'
• preventclosing: Boolean. Prevents closure of overlay via standard x button or escape key. For use when you are directing the user to somewhere else. Only valid with modal set to true.
• customclose: Boolean. If you do not use the header, but want to provide a close button in your html / src (with a class of o-overlay__close), setting customclose to true will attach o-overlay's close handler function to that button.
• parentnode: String. Should be a query selector for a DOM element. If set, the overlay will be appended as a child of this rather than the document body or target. If multiple nodes are matched, it will use the first. If nothing matches this selector, the body will be used.
• nested: Boolean. If set to true, the resize and escape key listeners will not be set up. This boolean should be used in conjunction with the parentnode setting to allow an overlay to be positioned within a DOM element rather than overlaid on top of everything. Default: false.
• nofocus: Boolean. If set to true, the tabindex will not be set on the wrapper element. Useful in conjunction with the nested and parentnode options. Default: false.
• layer: Boolean. If set to true, the overlay will close when new overlays are created. It will fire oOverlay.layerOpen and oOverlay.layerClose events when created and destroyed. You may want to set this to false if using a nested overlay. Default: true.

The only option that must be set is either src or html. The html option can't be set as a data- attribute, and if you set both, the html one will override src.

For compact overlays, headings can't be shaded as this looks weird too.

Data- attributes have the same name as in the JSON format, but with dashes. So for src it will be data-o-overlay-src and for the heading.title it will be data-o-overlay-heading-title.

o-overlays will throw an error if the options aren't set correctly.

API Overview

Static methods

• getOverlays(): Returns an array of all overlays on the page
• init([el]): Instantiates Overlays for all o-overlay-trigger elements within el (or document.body if not specified)
• destroy(): Destroys all Overlay objects and unbinds event handlers from trigger elements.

Object methods

• open: Display the overlay. Content is loaded every time the overlay is opened.
• close: Close (hide) the overlay.
• realign: Realign the overlay. Useful when overlay content changes whilst the overlay is open.

Events

• oOverlay.layerOpen: Is dispatched right before the overlay appears and indicates other overlays should be closed, when the layer option is set to true.
• oOverlay.layerClose: Is dispatched right after the overlay is removed, when the layer option is set to true.
• oOverlay.ready: Is dispatched when the overlay is loaded in the DOM. The ready event includes a detail.instance property of the initialised o-overlay instance.
• oOverlay.destroy: Is dispatched when the overlay is removed from the DOM.

Troubleshooting

• IE8 throws an error when closing the Overlay starting on the second time. It works like expected in spite of the error.
• Safari and Chrome mobile don't support the autofocus attribute. In Chrome mobile, you can use the .focus() function on an element when oOverlay.ready is dispatched to simulate the behaviour.
• In Safari mobile on iOS8, autofocus is buggy and is triggered after the overlay has loaded and a touchdown event is dispatched after that. That means that if you click anywhere on the page after the page loads, the keyboard will come up which will most likely produce unexpected behaviours. We recommend not using autofocus in iOS 8. These unexpected behaviours only occur the first time an overlay is rendered, after that, autofocus won't be activated.

Migration Guide

State	Major Version	Last Minor Release	Migration guide
✨ active	4	N/A	migrate to v4
⚠ maintained	3	3.1	migrate to v3
⚠ maintained	2	2.7	migrate to v2
╳ deprecated	1	1.17.0	N/A

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.

---

Licence

This software is published by the Financial Times under the MIT licence.