Origami Frontend Components & Services

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


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


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>

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>


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 */


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 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';

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

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


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

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

Option reference

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

Object methods



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


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.


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

Switch component view

GitHub: o-overlay@4.2.8

Install o-overlay

If using the Build Service, add o-overlay@^4.2.8 to your script and link tags.

If using the npm package manager for a Manual Build, run npm install --save-peer "@financial-times/o-overlay@^4.2.8".

Help & Support

o-overlay is maintained directly by the Origami team. If you have any questions about o-overlay or Origami in general, we are happy to help. 😊

Slack: #origami-support
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #origami-support
Email: origami.support@ft.com