Tooltip

Display additional information in a floating box on user interaction. Great for providing context and extra details without clutter.

ARIA design pattern

Getting started

There are several ways to initiate a tooltip, the simplest one is to add a data-ui-tooltip attribute to designate an anchor and add a title or data-tooltip-content attribute for the content.

<button data-ui-tooltip title="Hello!" class="my-tooltip-anchor">Hover me</button>

After that, you need to call Tooltip.initAll().

import { Tooltip } from "jolty";
Tooltip.initAll();

Next, through CSS, we set the styles for the tooltip and offset from the anchor using a CSS variable.

.tooltip {
  --ui-tooltip-offset: 1rem;
  background-color: white;
  color: black;
}

If some anchor’s styles or options are different from those we specified for .tooltip, we can overwrite them by adding our custom class by the data-ui-tooltip-class attribute.

<button data-ui-tooltip class="my-tooltip-anchor" data-ui-tooltip-class="tooltip--special" title="Hello!">
  Hover me
</button>

However, if we want to change the positioning, margin, and so on, we can set them for the anchor, they will overwrite the ones specified for ui-tooltip.

.my-tooltip-anchor {
  --ui-tooltip-placement: top-end;
  --ui-tooltip-offset: 1.5rem;
}

You can also set the default options via the static method Tooltip.data().

After which, they will be available through data-ui-tooltip="my-tooltip" or through options data: 'my-tooltip'.

import { Tooltip } from "jolty";
Tooltip.data("my-tooltip", {
  placement: "top",
  breakpoints: {
    1024: {
      placement: "top-end",
    },
  },
});
Tooltip.initAll();

Options

Name	Type	Default	Description
`init`	`Boolean`	`true`	Should the instance be automatically initialized when an instance is created? If `false`, you’ll need to manually initiate it by calling `tooltip.init()`.
`destroy`	`Boolean`	`false`	Allows you to destroy an instance at a specific breakpoint.
`data`	`String`	`''`	Allows you to use the default options that have been added by the `Tooltip.data()` static method.
`on`	`Object`	`null`	Used to register event handlers.
`appear`	`Boolean`	`null`	If you want to apply a transition upon initialization as well, you can set this option to `true`. Attribute: `data-ui-appear`
`eventPrefix`	`String`	`'ui-tooltip:'`	Prefix for events dispatched on the `anchor` element.
`eventDispatch`	`Boolean`	`true`	Defines if events are dispatched or used only within options.
`eventBubble`	`Boolean`	`true`	Defines if events should bubble up the DOM.
`breakpoints`	`Object`	`null`	Defines custom options for specific breakpoints.
`shown`	`Boolean`	`null`	Defines if the tooltip is expanded after initialization. By default, it’s `null`, which means it checks the `hidden` attribute or another attribute, depending on `stateMode`.
`awaitAnimation`	`Boolean`	`false`	Determines whether to wait for the end of the animation to trigger `'shown','hidden'` events and return a promise.
`backDismiss`	`Boolean`	`true`	Whether to close the tooltip when the `Escape` key is pressed.
`outsideHide`	`Boolean`	`true`	Whether to close the tooltip when clicking outside of it.
`interactive`	`Boolean`	`false`	Determines whether it is possible to interact with the `tooltip` using the keyboard and cursor.
`anchorClassActive`	`String`	`'ui-active'`	CSS class for `anchor` when `tooltip` is open.
`tooltipClassActive`	`String`	`'ui-active'`	CSS class for `tooltip` when it’s open.
`tooltipClass`	`String`	`''`	Adds a CSS class for the the `tooltip`. Attribute: `data-ui-tooltip-class`
`trigger`	`String`	`'hover focus'`	tooltip supports triggers by `'click'`, `'hover'` and `'focus'`. You may pass multiple triggers; separate them with a space. Attribute: `data-ui-trigger`
`template`	`Function`	`null`	Defines the HTML structure for the `tooltip`.
`content`	`any`	`null`	The tooltip content. By default, it is taken from the `data-ui-tooltip-content` attribute, if it is not added, then from the `title` attribute. Attribute: `data-ui-content`
`removeTitle`	`Boolean`	`true`	Determines whether to remove the `title` attribute during initialization. It is returned back after `destroy`.
`returnFocus`	`Boolean`	`true`	Defines whether focus should return to the element that triggered it. You can also pass an object with the option `{await: true}`, which indicates that it should wait for the end of the transition to return focus.
`focusTrap`	`Boolean`	`false`	Defines whether the focus must be trapped inside the `tooltip`.
`dismiss`	`Boolean, CSSSelector`	`true`	Allows the tooltip to be hide when clicked on the button. By default, it’s `true`, meaning the `hide()` method will be called when `'[data-ui-dismiss=""],[data-ui-dismiss="tooltip"]'` is clicked.
`topLayer`	`Boolean`	`true`	Determines whether the `tooltip` should be displayed in the top layer. CSS Variable: `--ui-tooltip-top-layer: 1;`
`root`	`Element`	`'body'`	The element to which the `tooltip` will be appended.
`moveToRoot`	`Boolean`	`false`	Moves the `tooltip` to the element defined in the `root` option when opened. CSS Variable: `--ui-tooltip-move-to-root: 0;`
`a11y`	`Boolean`	`true`	Adds `aria-describedby` attribute to the `anchor` and `role="tooltip"` to the `tooltip`.

Floating

Name	Type	Default	Description
`placement`	`String`	`'top'`	How to position the tooltip: Use `'top','bottom','left'`, or `'right'`. You can also append `'-start'` or `'-end'` to these positions for better alignment of the tooltip, such as `'top-start'`. You can also use the `'dialog'` value, in which case the `tooltip` will be displayed as a dialog, without being attached to the `anchor`. Attribute: `data-ui-placement` CSS Variable: `--ui-tooltip-placement: bottom;`
`delay`	`Number`	`[150, 0]`	Sets delay when `trigger:'hover'`. Accepts 2 values, for `mouseevent` and `mouseleave`, if one value is set, it applies to both.
`offset`	`Number`	`0`	Specifies the offset between the tooltip and its anchor. CSS Variable: `--ui-tooltip-offset: 0px;`
`padding`	`Number, Number`	`0`	Specifies padding from the `anchor`’s borders. It accepts two values: padding from the `start` and from the `end`. If a single value is given, it will be applied to both sides. CSS Variable: `--ui-tooltip-padding: 0px;`
`flip`	`Boolean, Boolean`	`true`	whether the `tooltip` should flip to the opposite placement when there’s not enough space. It can accept two values, corresponding to the X and Y axes. CSS Variable: `--ui-tooltip-flip: 1;`
`sticky`	`Boolean`	`true`	Defines whether the `tooltip` should shift to stay in view during a scroll. CSS Variable: `--ui-tooltip-sticky: 1;`
`shrink`	`Boolean`	`false`	Defines whether the `tooltip` should decrease in size to fit when there’s insufficient space. Remember that you must use the generated CSS variables to apply the available sizes. CSS Variable: `--ui-tooltip-shrink: 0;`
`boundaryOffset`	`Number, Number[], Object`	`0`	Specifies padding from the relative parent’s borders. It can accept up to four values like inset or margin CSS properties. You can also specify an object (for JS only) in the form `{top: 0, right: 0, bottom: 0, left: 0}` CSS Variable: `--ui-tooltip-boundary-offset: 0px;`

Arrow

Name	Type	Default	Description
`arrow`	`Boolean, Object`	`true`	Object with arrow options or `false` to disable.

`width`	`Number`	`0`	Sets the width of the arrow. By default, it gets the width of the `data-ui-tooltip-arrow` element. CSS Variable: `--ui-tooltip-arrow-width: 0px;`
`height`	`Number`	`0`	Sets the height of the arrow. By default, it gets the height of the `data-ui-tooltip-arrow` element. CSS Variable: `--ui-tooltip-arrow-height: 0px;`
`offset`	`Number`	`0`	Sets the arrow’s offset from the `tooltip`. CSS Variable: `--ui-tooltip-arrow-offset: 0px;`
`padding`	`Number`	`0`	Sets padding from the `tooltips`’s borders. It accepts two values: padding from the `start` and from the `end`. If a single value is given, it will be applied to both sides. CSS Variable: `--ui-tooltip-arrow-padding: 0px;`

Transition

Attribute	Type	Default	Description
`transition`	`String, Boolean, TransitionOptions`	`true`	Object with transition options or string to set the `name` option for the transition.

`name`	`String`	`'ui'`	Defines the name of the transition that will be used to apply CSS rules. Attribute: `data-ui-transition-name`
`css`	`Boolean`	`true`	Defines if the transition should be applied using CSS rules.
`cssVariables`	`Boolean`	`false`	Adds special CSS variables during the transition to the `tooltip` element and removes them after completion.
`enter`	`Function`	`null`	Accepts a function `enter(el, done){}`. call the `done()` callback to indicate transition end
`enterActive`	`String, Object`	`''`	CSS classes or styles applied during the entire entering phase. Attribute: `data-ui-enter-active`
`enterFrom`	`String, Object`	`''`	CSS classes or styles applied at the start of the entering phase. Attribute: `data-ui-enter-from`
`enterTo`	`String, Object`	`''`	CSS classes or styles applied at the end of the entering phase. Attribute: `data-ui-enter-to`
`leave`	`Function`	`null`	Accepts a function `leave(el, done){}`. call the `done()` callback to indicate transition end
`leaveActive`	`String, Object`	`''`	CSS classes or styles applied during the entire leaving phase. Attribute: `data-ui-leave-active`
`leaveFrom`	`String, Object`	`''`	CSS classes or styles applied at the start of the leaving phase. Attribute: `data-ui-leave-from`
`leaveTo`	`String, Object`	`''`	CSS classes or styles applied at the end of the leaving phase. Attribute: `data-ui-leave-to`
`duration`	`Number`	`null`	Defines the duration of the transition. Should be used only when the animation occurs on child elements.

If the cssVariables option is enabled, special CSS variables are added during the transition to tooltip and are removed after its completion.

Name	Type	Description
`--ui-transition-width`	`Number`	The width of the `tooltip` element at the start of the transition.
`--ui-transition-height`	`Number`	The height of the `tooltip` element at the start of the transition.

CSS Variables

Name	Type	Description
`--ui-floating-width`	`Number`	The width of the `tooltip`.
`--ui-floating-height`	`Number`	The height of the `tooltip`.
`--ui-floating-anchor-width`	`Number`	The width of the `anchor`.
`--ui-floating-anchor-height`	`Number`	The height of the `anchor`.
`--ui-floating-available-width`	`Number`	The remaining width between the `anchor` and the boundary edge. Only when the `shrink` option is enabled.
`--ui-floating-available-height`	`Number`	The remaining height between the `anchor` and the boundary edge. Only when the `shrink` option is enabled.
`--ui-floating-arrow-left`	`Number`	The left offset for the arrow.
`--ui-floating-arrow-top`	`Number`	The top offset for the arrow.
`--ui-floating-transform-origin`	`Number`	The `transform-origin` computed from the content and arrow position

Methods

Name	Return	Description
`init()`	`instance`	Initializes the component.
`destroy(destroyOptions)`	`instance, null`	Destroys the component and accepts an object as a option `{ remove: false, keepInstance: false, keepState: false }`.
`update(options)`	`instance`	Accepts options as an argument and updates the component.
`toggle(toggleOptions, force)`	`promise`	Toggles the component’s visibility state between shown and hidden. Accepts `true` or `false` as a option, which sets the `animated` option or an object `{ animated: true, silent: false }`.
`show(toggleOptions)`	`promise`	Opens the component and accepts the same options as the `toggle()` method.
`hide(toggleOptions)`	`promise`	Closes the component and accepts the same options as the `toggle()` method.

Class Methods

Name	Return	Description
`toggle(id, force, toggleOptions)`	`promise`	Searches for an instance by `id` and calls its `toggle()` method with the specified options.
`show(id, toggleOptions)`	`promise`	Searches for an instance by `id` and calls its `show()` method with the specified options.
`hide(id, toggleOptions)`	`promise`	Searches for an instance by `id` and calls its `hide()` method with the specified options.
`data(name?, data)`	`Class`	Sets default options for components that have the property `data:'name'` or by the attribute `data-ui-tooltip="name"`.
`updateDefault(options)`	`options`	Updates default options.
`initAll(root)`	`instance`	Searches for elements in `root`, which defaults to `document` with the attribute `data-ui-tooltip` and initializes them.
`get(id or elem)`	`instance`	Searches for an instance by `id` or element (checks the `base` property).
`getOrCreate(id or elem, options)`	`instance`	Searches for an instance by `id` or element (checks the `base` property), if not found, creates a new instance with specified options.

Properties

Name	Type	Description
`id`	`String`	The `id` of the `base` / `tooltip` element.
`isInit`	`Boolean`	Indicates whether the instance is already initialized.
`opts`	`Object`	Contains the currently applied options for the current breakpoint.
`baseOpts`	`Object`	Contains all options, including the `breakpoints` option.
`base, anchor`	`Element`	All components have a `base` property, which refers to the element through which the component is initialized and where events are fired. `anchor` is the same as `base`.
`tooltip`	`Element`	The element that contains the tooltip content.
`isOpen`	`Boolean`	Indicates whether the tooltip is currently shown.
`initialPlaceNode`	`Node`	Reference to the node that is located where the tooltip was at the moment of initialization.

Class properties

Name	Type	Description
`Default`	`Object`	Contains the default options for all instances.
`instances`	`Map`	A `Map` that contains all instances of the `Tooltip` class.

Events

Name	Arguments	Description
`beforeInit`	`instance`	Event will fired right before initialization.
`init`	`instance`	Fires when initialization has been completed.
`beforeShow`	`instance, {trigger, event}`	Fires immediately when the `show()` method is called.
`show`	`instance, {trigger, event}`	Fires when the element becomes visible, but the CSS transition hasn’t started yet.
`shown`	`instance, {trigger, event}`	Fires when the CSS transition hasn’t been completed.
`beforeHide`	`instance, {trigger, event}`	Fires immediately when the `hide()` method is called.
`hide`	`instance, {trigger, event}`	Fires just before the CSS transition starts.
`hidden`	`instance, {trigger, event}`	Fires when the CSS transition has been completed.
`beforeDestroy`	`instance`	Fires before the instance is destroyed.
`destroy`	`instance`	Fires immediately when the `destroy()` method is called.
`breakpoint`	`instance, breakpoint, prevBreakpoint`	Fires when the breakpoint has been changed.
`any`	`eventName, instance`	Fires on any event occurrence. The first argument contains the name of the event.