Jolty home Jolty Documentation

Tooltip

Display additional information in a small floating box when a user interacts with an element.
<button class="btn btn--md btn--primary" data-ui-tooltip title="Hello!">Hover me</button>

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="tooltip-anchor">Hover me</button>

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

js
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.

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

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

<button
  data-ui-tooltip
  class="tooltip-anchor"
  data-ui-tooltip-class="ui-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.

.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

NameTypeDefaultDescription
initBooleantrueShould the instance be automatically initialized when an instance is created? If false, you’ll need to manually initiate it by calling tooltip.init().
destroyBooleanfalseAllows you to destroy an instance at a specific breakpoint.
dataString''Allows you to use the default options that have been added through the Tooltip.data() static method.
onObjectnullUsed to register event handlers.
appearBooleannullIf you want to apply a transition upon initialization as well, you can set this option to true. Attribute: data-ui-appear
eventPrefixString'ui-tooltip:'Prefix for events dispatched on the anchor element.
eventDispatchBooleantrueDefines if events are dispatched or used only within options.
eventBubbleBooleantrueDefines if events should bubble up the DOM.
breakpointsObjectnullDefines custom options for specific breakpoints.
shownBooleannullDetermines if the tooltip is expanded after initialization. By default, it’s null, which means it checks the hidden attribute or another attribute, depending on hideMode.
awaitAnimationBooleanfalseDetermines whether to wait for the end of the animation to trigger 'shown','hidden' events and return a promise.
escapeHideBooleantrueWhether to close the tooltip when the Escape key is pressed.
outsideHideBooleantrueWhether to close the tooltip when clicking outside of it.
interactiveBooleanfalseDetermines whether it is possible to interact with the tooltip using the keyboard and cursor.
anchorClassActiveString'ui-active'CSS class for anchor when tooltip is open.
tooltipClassActiveString'ui-active'CSS class for tooltip when it’s open.
tooltipClassString''Adds a CSS class for the the tooltip. Attribute: data-ui-tooltip-class
floatingClassString''Adds a CSS class for the floating wrapper around the tooltip. Attribute: data-ui-floating-class
triggerString'hover focus'tooltip supports triggers by 'click', 'hover' and 'focus'. You may pass multiple triggers; separate them with a space. Attribute: data-ui-trigger
templateFunctionnullDefines the HTML structure for the tooltip.
contentanynullThe 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
removeTitleBooleantrueDetermines whether to remove the title attribute during initialization. It is returned back after destroy.
returnFocusBooleantrueDefines 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.
focusTrapBooleanfalseDefines whether the focus must be trapped inside the tooltip.
dismissBoolean, CSSSelectortrueAllows 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.
topLayerBooleantrueDetermines whether the tooltip should be displayed in the top layer. CSS Variable: --ui-tooltip-top-layer: true;
rootElement'body'The element to which the tooltip will be appended.
moveToRootBooleanfalseMoves the tooltip to the element defined in the root option when opened. CSS Variable: --ui-tooltip-move-to-root: false;
a11yBooleantrueAdds aria-describedby attribute to the anchor and role="tooltip" to the tooltip.

Floating

NameTypeDefaultDescription
placementString'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-dropdown-placement: bottom;
delayNumber[150, 0]Sets delay when trigger:'hover'. Accepts 2 values, for mouseevent and mouseleave, if one value is set, it applies to both.
offsetNumber0Specifies the offset between the tooltip and its anchor. CSS Variable: --ui-tooltip-offset: 0px;
paddingNumber, Number0Specifies 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;
flipBoolean, Booleantruewhether 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: true;
stickyBooleantrueDefines whether the tooltip should shift to stay in view during a scroll. CSS Variable: --ui-tooltip-sticky: true;
shrinkBooleanfalseDefines 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: false;
boundaryOffsetNumber, Number[], Object0Specifies 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

NameTypeDefaultDescription
arrowBoolean, ObjecttrueObject with arrow options or false to disable.
widthNumber0Sets 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;
heightNumber0Sets 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;
offsetNumber0Sets the arrow’s offset from the tooltip. CSS Variable: --ui-tooltip-arrow-offset: 0px;
paddingNumber0Sets 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

AttributeTypeDefaultDescription
transitionString, Boolean, TransitionOptionstrueObject with transition options or string to set the name option for the transition.
nameString'ui'Defines the name of the transition that will be used to apply CSS rules. Attribute: data-ui-transition-name
cssBooleantrueDefines if the transition should be applied using CSS rules.
cssVariablesBooleanfalseAdds special CSS variables during the transition to the tooltip element and removes them after completion.
enterFunctionnullAccepts a function enter(el, done){}. call the done() callback to indicate transition end
enterActiveString, Object''CSS classes or styles applied during the entire entering phase. Attribute: data-ui-enter-active
enterFromString, Object''CSS classes or styles applied at the start of the entering phase. Attribute: data-ui-enter-from
enterToString, Object''CSS classes or styles applied at the end of the entering phase. Attribute: data-ui-enter-to
leaveFunctionnullAccepts a function leave(el, done){}. call the done() callback to indicate transition end
leaveActiveString, Object''CSS classes or styles applied during the entire leaving phase. Attribute: data-ui-leave-active
leaveFromString, Object''CSS classes or styles applied at the start of the leaving phase. Attribute: data-ui-leave-from
leaveToString, Object''CSS classes or styles applied at the end of the leaving phase. Attribute: data-ui-leave-to
durationNumbernullDefines 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.

NameTypeDescription
--ui-transition-widthNumberThe width of the tooltip element at the start of the transition.
--ui-transition-heightNumberThe height of the tooltip element at the start of the transition.

CSS Variables

NameTypeDescription
--ui-tooltip-widthNumberThe width of the tooltip.
--ui-tooltip-heightNumberThe height of the tooltip.
--ui-tooltip-anchor-widthNumberThe width of the anchor.
--ui-tooltip-anchor-heightNumberThe height of the anchor.
--ui-tooltip-available-widthNumberThe remaining width between the anchor and the boundary edge.
Only when the shrink option is enabled.
--ui-tooltip-available-heightNumberThe remaining height between the anchor and the boundary edge.
Only when the shrink option is enabled.
--ui-tooltip-arrow-leftNumberThe left offset for the arrow.
--ui-tooltip-arrow-topNumberThe top offset for the arrow.
--ui-tooltip-transform-originNumberThe transform-origin computed from the content and arrow position

Methods

NameReturnDescription
init()instanceInitializes the component.
destroy(destroyOptions)instance, nullDestroys the component and accepts an object as a option { remove: false, keepInstance: false, keepState: false }.
update(options)instanceAccepts options as an argument and updates the component.
toggle(toggleOptions, force)promiseToggles 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)promiseOpens the component and accepts the same options as the toggle() method.
hide(toggleOptions)promiseCloses the component and accepts the same options as the toggle() method.

Class Methods

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

Properties

NameTypeDescription
idStringThe id of the base / tooltip element.
isInitBooleanIndicates whether the instance is already initialized.
optsObjectContains the currently applied options for the current breakpoint.
baseOptsObjectContains all options, including the breakpoints option.
base, anchorElementAll 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.
tooltipElementThe element that contains the tooltip content.
isOpenBooleanIndicates whether the tooltip is currently shown.
initialPlaceNodeNodeReference to the node that is located where the tooltip was at the moment of initialization.

Class properties

NameTypeDescription
DefaultObjectContains the default options for all instances.
instancesMapA Map that contains all instances of the Popover class.

Events

By default, events that are listened to directly through an element have the prefix 'ui-tooltip:'. This can be changed through the eventPrefix property. Additionally, you can disable the bubbling of these events using eventBubble or turn them off entirely via eventDispatch.

tooltip.data("my-tooltip", {
  on: {
    shown(instance, { trigger, event }) {
      // do something...
    },
    any(eventName, instance, { trigger, event }) {
      if (eventName === "shown") {
        // do something...
      }
    },
  },
});
 
// or directly on the tooltip element
const tooltipElem = document.querySelector(".my-tooltip");
tooltipElem.addEventListener("ui-tooltip:show", (e) => {
  const [instance, { trigger, event }] = e.detail;
  // do something...
});
 
// or on the document
document.addEventListener("ui-tooltip:show", (e) => {
  const [instance, { trigger, event }] = e.detail;
  // do something...
});
NameArgumentsDescription
beforeInitinstanceEvent will fired right before initialization.
initinstanceFires when initialization has been completed.
beforeShowinstance, {trigger, event}Fires immediately when the show() method is called.
showinstance, {trigger, event}Fires when the element becomes visible, but the CSS transition hasn’t started yet.
showninstance, {trigger, event}Fires when the CSS transition hasn’t been completed.
beforeHideinstance, {trigger, event}Fires immediately when the hide() method is called.
hideinstance, {trigger, event}Fires just before the CSS transition starts.
hiddeninstance, {trigger, event}Fires when the CSS transition has been completed.
beforeDestroyinstanceFires before the instance is destroyed.
destroyinstanceFires immediately when the destroy() method is called.
breakpointinstance, breakpoint, prevBreakpointFires when the breakpoint has been changed.
anyeventName, instanceFires on any event occurrence. The first argument contains the name of the event.
2023 © A Project by Jolty Labs 🇪🇸 🇺🇦