JointJS+ Tooltip

ui.Tooltip

Use tooltips to display information messages anywhere in the UI.

Installation

Include joint.ui.tooltip.css and joint.ui.tooltip.js files to your HTML:

<link rel="stylesheet" type="text/css" href="joint.ui.tooltip.css">
<script src="joint.ui.tooltip.js"></script>

Creating a Tooltip

A tooltip can be created with the joint.ui.Tooltip constructor. One instance of joint.ui.Tooltip manages multiple tooltips. Tooltips has configuration on html elements, as data attributes. Configuration passed in constructor became global settings for the particular tooltip. Setting defined as a data attribute won't override the global setting defined in the constructor. Newly added elements with a known definition are initialized automatically, right after append.

// js part - initialize tooltip
new joint.ui.Tooltip({
    target: '[data-tooltip]',
    direction: 'auto',
    padding: 10
});

<!-- html part - tooltip configuration -->
<label data-tooltip="Top directed tooltip" data-tooltip-position="top">Hover to see top tooltip</label>
<label data-tooltip="Left directed tooltip" data-tooltip-position="left">Hover to see left tooltip</label>
<label data-tooltip="Right directed tooltip" data-tooltip-position="right">Hover to see right tooltip</label>
<label data-tooltip="Bottom directed tooltip" data-tooltip-position="bottom">Hover to see bottom tooltip</label>

Result

In this demo all the elements with the data attribute tooltip will display tooltip when hovered.

Configuration

The joint.ui.Tooltip constructor takes the following parameters:

target string | Element | jQuery A CSS selector, DOM element or jQuery object that is the target for the tooltip. When the user hovers over this element with his mouse cursor, the tooltip appears.

rootTarget string | Element | jQuery A CSS selector, DOM element or jQuery object that is the root target for the tooltip. When using the `rootTarget`, the event handlers that trigger the tooltip display will be delegated (as opposed to directly-bound). This is useful when the `target` is a selector pointing to elements that might get removed from the DOM and then put back again. The tooltip tries to find the selected elements specified by the selector in the `target` option when it is initialized (during instantiation) and than uses these element as the target for the tooltip. If later on such elements are removed from the DOM the tooltip looses a reference to the target. Therefore, we can prevent this by using `rootTarget` or selecting the container element and `target` selector for selecting the real target of the tooltip at the time of the `"mouseover"` event.

container string | Element | jQuery A CSS selector, DOM element or jQuery object that is the container element, which the tooltip is appended to. Later when the tooltip is shown it respects the boundary of this container and changes its direction if it would overlap the boundary.

content string | Element | jQuery | function(element, tooltip) The content of the tooltip. It can be an arbitrary string/HTML or a function. The element parameter is undefined when the user calls show or toggle API methods with the point as a parameter. If the function returns null or undefined the content is taken from data-tooltip (or arbitrary place using dataAttributePrefix parameter). If the function returns false the tooltip is not displayed.

padding string | Element | jQuery | function(element) The distance between `target` element and the tooltip.

position string | function(element) The position of the element relative to the tooltip. `left` means the element is on the left of the shown tooltip. Can be either `top`, `left`, `bottom`, `right`

direction string | function(element) The direction of the tooltip arrow. Can be either `top`, `right`, `bottom`, `left` or `auto`. `auto` sets the arrow accordingly to 'position' property. Arrows are disabled if the `direction` is a falsy value or `off`

positionSelector string | Element | jQuery | function(element) A CSS selector or DOM element or jQuery object or a function used to compute the position of the edge of the tooltip. It defines bounding box which the tooltip mustn't to get across.

trigger string Event which makes the tooltip show up. Can be either `hover`, `focus` or `click`. This option cannot be set as a data attribute on the DOM element.

minResizedWidth number A minimal width of the tooltip. The tooltip width can be resized down to the `minResizedWidth`. If the available space is smaller than the `minResizedWidth`, the direction of the tooltip is changed to its opposite direction (left tooltip is swapped to right, top to bottom and vice versa). Set `minResizedWidth` to a falsy value if no automatic resizing or direction swapping should take a place. It defaults to `100`.

hideTrigger

string

Event which makes the tooltip disappear. Can be any of the DOM event. Separate multiple events with `' '`.

<label data-tooltip="tooltip text" data-tooltip-hide-trigger="mouseout mouseover">HIDE ON MOUSEOUT</label>

new joint.ui.Tooltip({
    rootTarget: '.click-tooltip',
    target: '[data-tooltip]',
    trigger: 'click',
    hideTrigger: 'mouseout'
});

viewport

object | function(element)

viewport defines the boundary for the tooltip. It guarantees that the tooltip's content will be rendered inside the `viewport` bounding box.

selector	string \| jQuery \| Element	CSS selector, Element or jQuery object defining the `viewport` DOM object. The element triggering tooltip should be rendered inside this element.
padding	number	Minimal distance from the `viewport` boundaries.

dataAttributePrefix

string | function(element)

Defines prefix for HTML data attributes with the tooltip configuration.

new joint.ui.Tooltip({
    target: '[custom-def]',
    dataAttributePrefix: 'custom-def'
});

matches with

<label data-custom-def="Tooltip content" data-custom-def-position-selector=".box2" data-custom-def-position="bottom">BOTTOM</label>

animation

boolean | object

When set to true a CSS fade-in animation is applied to the tooltip. Passing an object with any of the following properties allows you to make further adjustments to the animation.

Property	Default	Description
duration	`'500ms'`	CSS animation-duration
delay	`'400ms'`	CSS animation-delay
timingFunction	`'ease'`	CSS animation-timing-function

Tooltip API

This API allows the user to manually control behaviour of the tooltip. When using the show or toggle method with the point option for closing the tooltip the user needs to call the hide or toggle method manually (there is no element to bind events).

show(options)	Shows current instance of the tooltip. The method accepts an optional `options` parameter which may contain a `target` (CSS selector or DOM Element) and/or coordinates (`x` and `y`) at which to create the tooltip.
hide()	Hides current instance of the tooltip.
toggle(options)	Toggles current instance of the tooltip. The method accepts an optional `options` parameter which may contain a `target` (CSS selector or DOM Element) and/or coordinates (`x` and `y`) at which to create the tooltip.
isVisible()	Returns `true` if the tooltip is hidden. Otherwise, returns `false`

Tooltip events

close	Triggered when the tooltip gets closed.

Tooltips in Halo

It's useful to show the user a hint on the Halo icon tools. Fortunately, it's very easy. For instance:


paper.on('cell:pointerup', function(cellView) {
    // We don't want a Halo for links.
    if (cellView.model instanceof joint.dia.Link) return;
    var halo = new joint.ui.Halo({ graph: graph, paper: paper, cellView: cellView });

    halo.changeHandle('remove', {
        attrs: {
            '.handle': {
                'data-tooltip-class-name': 'small',
                'data-tooltip': 'Click to remove the object',
                'data-tooltip-position': 'right'
            }
        }
    });

});

// run this once
new joint.ui.Tooltip({
    rootTarget: document.body,
    target: [data-tooltip],
    padding: 15
});

Notice we use the 'small' className in our example. JointJS+ tooltips come with two build-in sizes for tooltips: small and normal. In order to enable the small version use 'small' as a className.