Origami Frontend Components & Services

Readme: o-tooltip

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

Usage

o-tooltip has Sass and JavaScript to show and hide a tooltip which points at a target.

Markup

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>

<div data-o-component="o-tooltip"
    data-o-tooltip-position="below"
    data-o-tooltip-target="declarative-tooltip-target"
    data-o-tooltip-show-on-construction=true
    id="my-tooltip-element">
    <div class='o-tooltip-content'>
        Some text to go in the tooltip
    </div>
</div>

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
    </button>
</div>

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

JavaScript

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

Sass

Mixin: oTooltip

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.

Migration Guide

State Major Version Last Minor Release Migration guide
✨ active 4 N/A migrate to v4
⚠︎ maintained 3 3.5 migrate to v3
╳ deprecated 2 2.3.7 migrate to v2
╳ deprecated 1 1.1.1 N/A

Contact

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.


Licence

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

Switch component view

GitHub Repository

Install o-tooltip

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

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

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: #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