This pattern allows you to easily add tooltips with a variety of behaviours to your website.
Tooltips are intended to display contextual information and function about the trigger element.
### Markup structure
Tooltips are shown when the mouse hovers over the triggering element,
and are hidden when the mouse leaves the triggering element.
The trigger can be changed to require a click on the triggering element
by adding a `click` option.
Tooltips will be positioned close to the element that triggered them,
with an arrow tip pointing to the centre of the triggering item. The
placement of the tip on the tooltip determines the positioning of the
tooltip. For example if the tip is placed at the right side of the
tooltip, it naturally follows that the tooltip itself will be placed to
the left of the triggering element.
The position of the tip within the tooltip can be specified with a
*position* property which specifies the preferred positions. This is
formatted as `[,preference]*`. The possible preferences are:
- `tl`: tip placed at the leftmost corner of the top side of the tooltip
- `tm`: tip placed at the middle of the top side tooltip
- `tr`: tip placed at the rightmost corner of the top side of the tooltip
- `rt`: tip placed at the top corner of the right side of the tooltip
- `rm`: tip placed at the middle of the right side tooltip
- `rb`: tip placed at the bottom corner of the right side of the tooltip
- `bl`: tip placed at the leftmost corner of the bottom side of the tooltip
- `bm`: tip placed at the middle of the bottom side tooltip
- `br`: tip placed at the rightmost corner of the bottom side of the tooltip
- `lt`: tip placed at the top corner of the left side of the tooltip
- `lm`: tip placed at the middle of the left side tooltip
- `lb`: tip placed at the bottom corner of the left side of the tooltip
This specifies that the preferred position of the tip is at the top left
side of the tooltip (placing the tooltip itself on the right side of the
link). Notice that the position is the first defined property so you can use
shorthand syntax directly. If the tooltip does not fit at that position
then the left-middle position is tried, and then the the right-top or if all
previous options failed the middle of the right side is tried. If the tooltip
does not fit at any of the preferred positions, then it will be
positioned at the location that has the most space, even if this is not
one of the preferred positions.
It is possible to force a specific tooltip position by adding the
### Sticky tooltips
By default, the tooltip disappears when the cursor is moved off the element or
the triggering element is clicked. If this is not desired behaviour, there is
the option to change the closing behaviour to `sticky` or to `close-button`.
With `sticky`, the tooltip will remain until the user clicks outside of the
tooltip, or on mobile, if the user clicks on the close button.
With the `close-button` option, the tooltip will only be closed if the close
button is clicked.
For example, setting closing to `sticky`:
### AJAX tooltips
The tooltip content can be loaded via an AJAX request by proving an ajax
This will load the contents of the `#myTip` element of
balloon-contents.html and display it in a tooltip.
### Generated markup
The first time the tooltip is shown the tip itself will be wrapped in a
new tooltip container. This container will be positioned correctly.
will be transformed into:
Please enter the full URL for the website.
for tooltips which fetch their content with an AJAX call the tooltip may
be temporarily shown with a progress indicator:
### Options reference
The tooltip can be configured through a `data-pat-tooltip` attribute.
The available options are:
| Property | Default value | Values | Description | Type |
| ----- | --------| -------- | ------- | ----------- |
| `position-list`| `auto` | `tl` `tm` `tr` `rt` `rm` `rb` `br` `bm` `bl` `lb` `lm` `lt` | The priority in which the pattern will try to position the tooltip. With the tooltip is positioned where the most space is on the screen. The two letters indicate the position of the triangle as opposed to the tooltip body. Adding `force` will force the tooltip position, even if it would end up out of view. | Multiple value |
| `position-policy` | `auto` | `auto` `force` | Policy used to place a tooltip: either always use a listed position, or allow other positions if no space is available for the listed positions. | Mutually exclusive |
| `trigger` | `click` | `click` `hover` | Sets on which user action the tooltip should appear. | Mutually exclusive |
| `source` | `title` | `ajax` `content` `title` | Select where the contents of the tooltip is taken from: AJAX loading of the link target, the contents of element or its title attribute. | Mutually exclusive |
| `delay` | `0` | *time* | `The delay for the tooltip to appear, expressed in milliseconds | Time |
| `mark-inactive` | `true` | `true` `false` | Should we add inactive class to the tooltip trigger? | Bool |
| `closing` | `auto` | `auto` `sticky` `close-button` | Auto means that the tooltip will disappear when the user clicks out of the tooltip, or — in case of hover triggered tooltips — hovers away from the trigger element. `close-button` will add a close button to the tooltip which must be used to close the tooltip. | Mutually exclusive |
| `class` | *none* | *class value* | Assigns a class to the tooltip. For instance to give a specific tooltip a different colour | |
| `ajax-data-type`| `html` | `html` `markdown` | Data type of content to be loaded when AJAX is used as source. | Mutually exclusive |
| `target` | `body` | *selector* | Selects where the tooltip container is appended in the DOM | |