Origami Frontend Components & Services

Readme: o-tooltip

o-tooltip is a component usually used for annotating or highlighting bits of user interface.


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


This HTML demonstrates the declarative way to instantiate o-tooltip. If you are using the Build Service or firing your own o.DOMContentLoaded event, this is all you need to create a tooltip.

<div class='demo-tooltip-target' id="declarative-tooltip-target">
    A bit of UI to annotate

<div data-o-component="o-tooltip"
    <div class='o-tooltip-content'>
        Some text to go in the tooltip

This HTML is an example of the imperative alternative:

<div class='demo-tooltip-container'>
    <button class='o-buttons o-buttons--big imperative-tooltip-target'>
        Button description text/icon

Attributes can be set declaratively, or passed in on instantiation in an options object. A full list of data attributes:


No code will run automatically unless you are using the Build Service.
You must either construct an o-tooltip object or fire an o.DOMContentLoaded event, which oTooltip listens for.

Constructing an o-tooltip

If you have setup your tooltip declaratively, the following applies:

import Tooltip from '@financial-times/o-tooltip';
const tooltipEl = Document.getElementById('my-tooltip-element');
const tooltip = new Tooltip(tooltipEl);

Alternatively, if you want to construct a tooltip imperatively, you can instantiate o-tooltip by passing in your target element and an options object.

import Tooltip from '@financial-times/o-tooltip';
const tooltipEl = document.querySelector('.imperative-tooltip-element');
const opts = {
    target: 'tooltip-target-imperative',
    content: 'Click to save to somewhere',
    showOnConstruction: true,
    position: 'right'

const tooltip = new Tooltip(tooltipEl, opts);

Since this creates the tooltip from scratch, it is important to include any declarative attributes (as listed above) in the options object, in addition to:

Create tooltip directly in the body

There are situations when a tooltip cannot be displayed next to an element (i.e: the parent of the element has overlow: hidden). For these type of situations the tooltip can be instantiated using the appendToBody configuration property, which will force the tooltip element to be created just before body tag closing.

import Tooltip from '@financial-times/o-tooltip';
const tooltipEl = document.querySelector('.imperative-tooltip-element');
const opts = {
    target: 'tooltip-target-imperative',
    content: 'Click to save to somewhere',
    showOnConstruction: true,
    position: 'above',
    appendToBody: true
const tooltip = new Tooltip(tooltipEl, opts);

Note! this property can only be used only when constructing the tooltip declaratively

Firing an oDomContentLoaded event

document.addEventListener('DOMContentLoaded', function() {
    document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));


The oTooltip mixin is used to output tooltip selectors and styles. This output includes all of the .o-tooltip classes:

@include oTooltip();
.o-tooltip {
    /* styles */
.o-tooltip-content {
    /* styles */
/* etc. */

There is full Sass documentation available in the Origami Registry.


Include the oTooltipAddTheme mixin to output a custom tooltip theme. The mixin accepts a name for your theme and a map of options:

The following example shows how to add a custom theme named "my-product-modifier", with a slate background and white foreground. Instead of "my-product-modifier" choose a descriptive name that includes your project name, so it's clear where the custom theme is added.

// Outputs CSS class o-tooltip--my-product-modifier.
// Uses an o-colors function to fetch Origami colour values.
@include oTooltipAddTheme('my-product-modifier', (
    'background-color': oColorsByName('slate'),
    'foreground-color': oColorsByName('white')

This will output a CSS class o-tooltip--[name]. Add this class to your tooltip to view your custom theme.

Migration Guide

State Major Version Last Minor Release Migration guide
✨ active 5 N/A migrate to v5
⚠︎ maintained 4 4.1 migrate to v4
╳ deprecated 3 3.5 migrate to v3
╳ deprecated 2 2.3.7 migrate to v2
╳ deprecated 1 1.1.1 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-tooltip@5.2.4

Install o-tooltip

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

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

Help & Support

o-tooltip is maintained directly by the Origami team. If you have any questions about o-tooltip 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