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.


O-overlay contains styles for the container (eg border and shadow) and layout styles (to place the overlay above the page content). It does not come with typographic styles, background colours, or buttons. Implementing projects should add these.

o-overlay supports silent mode, so there are mixins for the different elements. If you want to get all the classes styled by default, you'll need to turn of silent mode:

$o-overlay-is-silent: false;


Static methods

Object methods


We implement o-layers events:

We also dispatch custom events:


Migration Guide

Migrating from 1.X.X to 2.X.X

- The o-colors and o-visual-effects dependencies have been bumped to the latest major. These will create bower conflicts which should be resolved by updating to the newest release of o-colors and o-visual-effects.


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


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

active Origami v1
Switch component view

GitHub Repository

Install o-overlay

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

If running a Manual Build, run npm install "o-overlay@^2.7.11".

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: #ft-origami
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: #ft-origami
Email: origami.support@ft.com