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:

const Tooltip = require('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.

const Tooltip = require('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.

const Tooltip = require('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

As with all Origami components, o-tooltip has a silent mode. To use its compiled CSS (rather than using its mixins with your own Sass) set $o-tooltip-is-silent : false; in your Sass before you've imported the o-tooltip Sass.

Migration Guide

Updating from v2 to v3

Updating from v1 to v2

V1 -> V2 introduces the new majors of o-overlay and o-visual-effects. Updating to this new version will mean updating any other components that you have which are using o-overlay or o-visual-effects. There are no other breaking changes in this release.


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@^3.2.3 to your script and link tags.

If running a Manual Build, run bower install --save "o-tooltip@^3.2.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