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.


o-overlay can be instantiated in two ways:


Set options as data- attributes on any element that has a o-overlay-trigger class, to create an overlay and open it when that element is clicked.

<button class="o-overlay-trigger" data-o-overlay-src="#overlay1-content" data-o-overlay-id="overlay1">Open!</button>
<script type="text/template" id="overlay1-content">
    <p>Content of overlay</p>

To activate overlays declared in markup, you can:


The constructor function 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.


Mixin: oOverlay

The oOverlay mixin is used to output base styles as well as styles for all of the overlay variants (compact, full-screen, and heading-shaded). This output includes the o-overlay class declarations:

@include oOverlay();
.o-overlay {
    /* styles */
.o-overlay--compact {
    /* styles */
.o-overlay--full-screen {
    /* styles */
/* etc. */

If you wish to specify specific variants to output styles for, you can pass in 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 master, internal, whitelabel
full-screen Included by default master, internal, whitelabel
header-shaded Included by default master, internal, whitelabel


Static methods

Object methods


We implement o-layers events:

We also dispatch custom events:


Migration Guide

State Major Version Last Minor Release Migration guide
✨ active 3 N/A 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.

Support Status
Switch component view

GitHub Repository

Install o-overlay

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

If running a Manual Build, run bower install --save "o-overlay@^3.0.5".

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