Readme: o-tooltip

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

Usage

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

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:

• data-o-tooltip-target: Required. An ID selector for the target of the tooltip (the thing it points to)
• data-o-tooltip-position: Optional. The preferred position of the tooltip relative to the target. Can be one of above, below, left, right. If there isn't room to render the tooltip where the option passed in would render it, this value is flipped (above becomes below, left becomes right). Defaults to below. You can also specify a different position per viewport width ('default', 'S', 'M', 'L', 'XL') eg data-o-tooltip-position-s="left". The position will fall back to the default in data-o-tooltip-position, otherwise 'below'.
• data-o-tooltip-show-on-construction: Optional. Boolean value. Set to true if you want the tooltip to be rendered immediately after it is constructed. Defaults to false.
• data-o-tooltip-show-on-hover: Optional. Boolean value. Set to true if you want to show and hide the tooltip based on the mouseover and mouseout events (respectively) of the target. Defaults to false.
• data-o-tooltip-show-on-focus: Optional. Boolean value. Set to true if you want to show and hide the tooltip based on the focusin and focusout events (respectively) of the target. Defaults to false.
• data-o-tooltip-show-on-click: Optional. Boolean value. Set to true if you want to show the tooltip upon clicking the target element. Defaults to false.
• data-o-tooltip-toggle-on-click: Optional. Boolean value. Set to true if you want to show and hide the tooltip by clicking on the target.
• data-o-tooltip-show-after: Optional. Integer value. Specify the number of seconds to wait before showing the tooltip. Only applies when data-o-tooltip-show-on-construction is set to false
• data-o-tooltip-close-after: Optional. Integer value. Specify the number of seconds to wait before closing the tooltip. Only applies when data-o-tooltip-show-on-construction is set to true
• data-o-tooltip-z-index: Optional. The z-index for the tooltip.
• data-o-tooltip-animation-distance: Optional. String with px suffix. Distance away from target to start and end animation. Defaults to '10px'.
• data-o-tooltip-append-to-body: Optional. Append the tooltip to the body element so it is positioned and sized according to the body rather than a parent element. By default the tooltip is appended as a sibling of the tooltip target. Defaults to false.

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 '@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:

• content: Required. String. This is the content that will be displayed in the tooltip.

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

Sass

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.

Customisation

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

• name: The name of your theme. This is used for the modifier class output o-tooltip--[name].
• opts: A map of options for your theme.
  • background-color: The background color for your tooltip.
  • foreground-color: The foreground/text color for your tooltip.
  • close-foreground-color (optional): The colour of the close button. If not set the foreground-color is used.

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

Contact

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.

Licence

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