jQuery.richTooltip

jQuery.richTooltip is a responsive tooltip which is designed to be optimized for both mouse and touch driven devices. It relies on Pointy.js to standardize user driven events.

Usage

Tooltips can be created both unobtrusively through data attributes or through a programmatic API.

Data attributes

By convention

You can create tooltips by convention using an <aside> element adjacent to any other element containing a the data-rel="tooltip" attribute.

	<a href="#" data-rel="tooltip">Help?</a>
	<aside>
		Your tooltip content!
	</aside>

With a selector

Alternatively you can specify the tooltip content element via the data-tooltip attribute giving a selector to tooltip content.

	<div>
		<a href="#" data-tooltip="#mytooltip">Help?</a>
	</div>
	..
	<aside id="mytooltip" class="rich-tooltip">
		Your tooltip content!
	</aside>

Programmatic API

To create a tooltip programmatically you simply call $(context).richTooltip(options);. Here is a simple example:

	$('#el').richTooltip({
		content: $('#mytooltip')
	});

The programmatic API allows you to also programmatically hide and show a tooltip via:

	// to show a tootlip
	$(context).richTooltip('show');

	// to hide a tooltip
	$(context).richTooltip('hide');

	// to toggle the tooltip
	$(context).richTooltip('toggle');

Events

richTooltip:open

A jQuery event richTooltip:open is triggered on the tooltip context whenever a wired up tooltip is opened.

	$(context).on('richTooltip:open', function (event, tooltip) {
		// tooltip will be the instance of the internal Tooltip class
	});

richTooltip:close

A jQuery event richTooltip:close is triggered on the tooltip context whenever a wired up tooltip is closed.

	$(context).on('richTooltip:close', function (event, tooltip) {
		// tooltip will be the instance of the internal Tooltip class
	});

Options

Position

Set via pos or data-tooltip-pos. Acceptable values are: north, east, south or west. This specifies the desired position for the tooltip to appear, however it is not a guarantee the tooltip will appear in the desired position. Positioning is determined by jquery.calcRestrainedPos.js, which calculates where the tooltip will be visible within the viewport, within any containers provided, and not overlapping any obstacles specified. Additionally on small screens, such as mobile devices, east and west directions are ignored and it will default to south if either is used.

Arrow Style

Set via the arrowStyle or data-tooltip-arrow-style. Known values are ‘outset’ or ‘inset’, by default the value is ‘outset’. This styling is used when calculating the optimized position for a tooltip. When the value is outset, the arrow is known to be outside the tooltip’s bounding box and therefore increases the positioning distance from the tooltip context. When the styling is inset, it is assumed the arrow is overlapping the tooltip.

Click behavior

The tooltip is designed to be fully responsive and to function on both touch- and mouse-driven devices. It supports two different behaviors:

• toggle on tap - the default behavior, which is to show the tooltip when the element is tapped (click or touch), and to hide it when there is a tap (click or touch) anywhere on the page.
• toggle on hover state (for mice), toggle on tap (for touch) - on desktop, the tooltip will be shown when the mouse hovers over the element, and will hide when the mouse is no longer hovering over either the element or the tooltip. However, on touch devices, the tooltip will be toggled (show/hide) each time the element is tapped.

To set the “hover” behavior:

• declaratively - use the attribute data-tooltip-action=”hover” in the div for the element
• programmatically - use the argument “action: ‘hover’” when invoking the richTooltip() function

Opt-out functionality

Don’t close on window resize

By default, tooltips are closed on window resize. If you’d like to disable this, you can either set the property closeOnWindowResize: false or add the data attribute data-tooltip-ignore-window-resize to the tooltip context.

Don’t close on document click

By default, tooltips are closed on document clicks that aren’t to the tooltip itself or its context. If you’d like to disable this, you can either set the property closeOnDocumentClick: false or add the data attribute data-tooltip-ignore-document-click to the tooltip context.