Tooltips

The Tooltip component shows contextual pop-ups on hover, providing additional information with customizable positions and styling.

Tooltips use the Popper library for dynamic positioning and viewport detection. Include popper.min.js before Hummingbird’s JavaScript, or use hummingbird.bundle.min.js / hummingbird.bundle.js, which include Popper. See the dependencies section for more details.

Tooltip components integrate Bootstrap's JavaScript plugins for interactivity, paired with custom styling for a unique and consistent user experience.

Class Name	Type	Description
tooltip	Component	Tooltip
tooltip-arrow	Inner	Tooltip arrow
tooltip-inner	Inner	Tooltip text box

Basic example

Tooltips must be initialized before use. They can be initialized by selecting elements with the data-bs-toggle attribute, as shown below:

HTML

<button type="button" class="btn btn-subtle-neutral" data-bs-toggle="tooltip" data-bs-title="Tooltip">Tooltip</button>

Directions

Hover over the buttons below to see tooltips in all four directions: top, right, bottom, and left.

HTML

<button type="button" class="btn btn-subtle-neutral" data-bs-toggle="tooltip" data-bs-placement="top" data-bs-title="Tooltip on top">Tooltip on top</button>
<button type="button" class="btn btn-subtle-neutral" data-bs-toggle="tooltip" data-bs-placement="right" data-bs-title="Tooltip on right">Tooltip on right</button>
<button type="button" class="btn btn-subtle-neutral" data-bs-toggle="tooltip" data-bs-placement="bottom" data-bs-title="Tooltip on bottom">Tooltip on bottom</button>
<button type="button" class="btn btn-subtle-neutral" data-bs-toggle="tooltip" data-bs-placement="left" data-bs-title="Tooltip on left">Tooltip on left</button>

Add a custom tooltip using data-bs-custom-class="custom-tooltip" for custom styling.

HTML

<button type="button" class="btn btn-subtle-neutral" data-bs-toggle="tooltip" data-bs-title="Custom Tooltip" data-bs-custom-class="custom-tooltip">Custom Tooltip</button>

Disabled elements

Elements with the disabled attribute aren’t interactive, meaning they cannot be focused, hovered, or clicked to trigger a tooltip (or popover). As a workaround, trigger the tooltip from a wrapper <div> or <span>.

HTML

<span class='inline-block' tabindex="0" data-bs-toggle="tooltip" data-bs-title="Disabled tooltip">
  <button class="btn btn-primary" type="button" disabled >Disabled button</button>
</span>

CSS variables

The tooltip component is built using a set of CSS variables. These variables provide flexibility for customizing styles.

.tooltip {
  --tooltip-zindex: 1080;
  --tooltip-max-width: 12.5rem;
  --tooltip-padding-x: --spacing(2.5);
  --tooltip-padding-y: --spacing(2);
  --tooltip-bg: var(--color-dark);
  --tooltip-color: var(--color-white);
  --tooltip-font-size: var(--text-xs);
  --tooltip-margin: --spacing(2);
  --tooltip-opacity: 1;
  --tooltip-border-radius: var(--radius-sm);
  --tooltip-arrow-width: 0.75rem;
  --tooltip-arrow-height: 0.53rem;
  --tooltip-arrow-border-radius: --spacing(0.5);
}

Usage

Use JavaScript in the familiar pattern of Bootstrap’s plugins with full additional TypeScript Support.

The tooltip plugin dynamically generates content and markup. By default, tooltips are positioned after their trigger element. A tooltip can be triggered via JavaScript as follows:

const exampleEl = document.getElementById('example')
const tooltip = new hummingbird.Tooltip(exampleEl, options)

Tooltips automatically attempt to adjust their positions when a parent container has overflow: auto or overflow: scroll, while still maintaining the original placement’s positioning. The boundary option (used for the flip modifier via the popperConfig option) can be set to any HTMLElement to override the default value, 'clippingParents', such as document.body:

const tooltip = new hummingbird.Tooltip('#example', {
  boundary: document.body // or document.querySelector('#boundary')
})

Markup

The essential markup for a tooltip includes only a data attribute and a title attribute on the HTML element intended to have a tooltip. The generated markup for a tooltip is relatively simple, though it requires a position (by default, set to top by the plugin).

To ensure tooltips are accessible to keyboard and assistive technology users, they should only be added to HTML elements that are inherently keyboard-focusable and interactive (such as links or form controls). While other HTML elements can be made focusable by adding tabindex="0", this can create disruptive and confusing tab stops on non-interactive elements for keyboard users. Most assistive technologies currently do not announce tooltips in such situations. Furthermore, avoid relying solely on hover as the trigger for tooltips, as this will make them inaccessible to keyboard users.

<!-- HTML to write -->
<a href="#" data-bs-toggle="tooltip" data-bs-title="Some tooltip text!">Hover over me</a>

<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-auto" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

Options

Options can be provided through data attributes or via JavaScript. When using data-bs-attributes, append the option’s name (e.g., data-bs-animation="{value}"). It is crucial to convert “camelCase” option names to “kebab-case” when passing options via data attributes. For instance, use data-bs-custom-class="beautifier" rather than data-bs-customClass="beautifier".

Tooltip component support data-bs-config data attribute. This attribute can contain simple component configurations as a JSON string. If an element has both data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456, as separate data attributes override values provided within data-bs-config. Additionally, existing data attributes can also house JSON values, such as data-bs-delay='{"show":0,"hide":150}'.

The ultimate configuration object results from merging data-bs-config, individual data-bs-attributes, and JavaScript objects, where the latest provided key-value pair takes precedence over others.

Note that for security reasons, the sanitize, sanitizeFn, and allowList options cannot be supplied using data attributes.

Name	Type	Default	Description
`allowList`	object	Default value	An object specifying allowed tags and attributes. Any not explicitly allowed will be removed by the content sanitizer. Exercise caution when adding to this list. Refer to OWASP’s Cross Site Scripting Prevention Cheat Sheet for more information.
`animation`	boolean	`true`	Applies a CSS fade transition to the tooltip.
`boundary`	string \| element	`'clippingParents'`	Defines the overflow constraint boundary of the tooltip (applies only to Popper’s preventOverflow modifier). By default, it is `'clippingParents'` and can accept an HTMLElement reference (via JavaScript only). For more information, refer to Popper’s detectOverflow documentation.
`container`	string \| element \| false	`false`	Appends the tooltip to a specific element. Example: `container: 'body'`. This option is particularly useful for positioning the tooltip in the document flow near the triggering element, which prevents it from drifting away during a window resize.
`customClass`	string \| function	`''`	Adds classes to the tooltip when it is shown. These classes are added in addition to any specified in the template. For multiple classes, separate them with spaces: `'class-1 class-2'`. A function returning a single string of additional class names can also be provided.
`delay`	number \| object	`0`	Specifies the delay (in ms) for showing and hiding the tooltip. This does not apply to manual trigger types. If a number is provided, the delay is applied to both hide and show. Object structure: `delay: { "show": 500, "hide": 100 }`
`fallbackPlacements`	array	`['top', 'right', 'bottom', 'left']`	Defines fallback placements by providing a list of placements in an array (in order of preference). For more information, refer to Popper’s behavior documentation.
`html`	boolean	`false`	Allows HTML content within the tooltip. If true, HTML tags in the tooltip’s `title` will be rendered. If false, the `innerText` property will be used to insert content into the DOM. For user-generated input, text is preferred to prevent XSS attacks.
`offset`	array \| string \| function	`[0, 6]`	Determines the offset of the tooltip relative to its target. A string with comma-separated values, such as `data-bs-offset="10,20"`, can be passed in data attributes. When a function is used to define the offset, it receives an object (containing the Popper placement, reference, and Popper rects) as its first argument, and the triggering element’s DOM node as the second. The function must return an array with two numbers: skidding and distance. For more information, refer to Popper’s offset documentation.
`placement`	string \| function	`'top'`	Specifies how to position the tooltip: auto, top, bottom, left, right. When `auto` is specified, the tooltip dynamically reorients itself. When a function is used to determine placement, it is called with the tooltip DOM node as its first argument and the triggering element DOM node as its second. The `this` context is set to the tooltip instance.
`popperConfig`	null \| object \| function	`null`	Allows modification of Bootstrap’s default Popper configuration. Refer to Popper’s configuration documentation. When a function is used to create the Popper configuration, it is called with an object containing Bootstrap’s default Popper configuration. This facilitates using and merging the default configuration with custom settings. The function must return a configuration object for Popper.
`sanitize`	boolean	`true`	Enables content sanitization. If true, the `template`, `content`, and `title` options will be sanitized. content sanitizer. Exercise caution when disabling content sanitization. Refer to OWASP’s Cross Site Scripting Prevention Cheat Sheet for more information. Vulnerabilities caused solely by disabling content sanitization are not considered within scope for Bootstrap’s security model.
`sanitizeFn`	null \| function	`null`	Provides an alternative content sanitization function. This can be useful if a dedicated library is preferred for sanitization.
`selector`	string \| false	`false`	If a selector is provided, tooltip objects will be delegated to the specified targets. In practice, this applies tooltips to dynamically added DOM elements (`jQuery.on` support). See this issue and an informative example. Note: The title attribute must not be used as a selector.
`template`	string	`'<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'`	The base HTML used when creating the tooltip. The tooltip’s `title` will be injected into the `.tooltip-inner`. The `.tooltip-arrow` will become the tooltip’s arrow. The outermost wrapper element should have the `.tooltip` class and `role="tooltip"`.
`title`	string \| element \| function	`''`	The tooltip title. If a function is provided, it will be called with its `this` reference set to the element the popover is attached to.
`trigger`	string	`'hover focus'`	Specifies how the tooltip is triggered: click, hover, focus, manual. Multiple triggers can be passed, separated by a space. `'manual'` indicates the tooltip will be triggered programmatically via the `.tooltip('show')`, `.tooltip('hide')`, and `.tooltip('toggle')` methods; this value cannot be combined with any other trigger. `'hover'` on its own will result in tooltips that cannot be triggered via the keyboard and should only be used if alternative methods for conveying the same information for keyboard users are present.

Data Attributes for Individual Tooltips

Options for individual tooltips can also be specified using data attributes, as previously explained.

using function with popperConfig:

const tooltip = new hummingbird.Tooltip(element, {
  popperConfig(defaultBsPopperConfig) {
    // const newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

Methods

All API methods are asynchronous and initiate a transition. They return to the caller immediately after the transition begins but before it concludes. Furthermore, a method call on a component that is already transitioning will be disregarded. More information is available in Bootstrap’s JavaScript documentation.

Method	Description
`disable`	Removes the ability for an element’s tooltip to be shown. The tooltip will only be able to be shown again if it is re-enabled.
`dispose`	Hides and destroys an element’s tooltip (removing stored data on the DOM element). Tooltips created using delegation (via the selector option) cannot be individually destroyed on descendant trigger elements.
`enable`	Restores an element’s tooltip with the ability to be shown. Tooltips are enabled by default.
`getInstance`	A static method allowing retrieval of the tooltip instance associated with a DOM element.
`getOrCreateInstance`	A static method that allows retrieval of the tooltip instance associated with a DOM element, or creates a new one if it has not been initialized.
`hide`	Conceals an element’s tooltip. It returns to the caller before the tooltip has actually been hidden (i.e., before the `hidden.bs.tooltip` event occurs). This is considered a “manual” triggering of the tooltip.
`setContent`	Provides a method to modify the tooltip’s content after its initialization.
`show`	Reveals an element’s tooltip. It returns to the caller before the tooltip has actually been shown (i.e., before the `shown.bs.tooltip` event occurs). This is considered a “manual” triggering of the tooltip. Tooltips with zero-length titles are never displayed.
`toggle`	Toggles an element’s tooltip between shown and hidden states. It returns to the caller before the tooltip has actually been shown or hidden (i.e., before the `shown.bs.tooltip` or `hidden.bs.tooltip` events occur). This is considered a “manual” triggering of the tooltip.
`toggleEnabled`	Toggles the ability for an element’s tooltip to be shown or hidden.
`update`	Updates the position of an element’s tooltip.

const tooltip = hummingbird.Tooltip.getInstance('#example') // Returns a hummingbird tooltip instance

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })

The setContent method accepts an object argument, where each property-key is a valid string selector within the tooltip template, and each related property-value can be a string, element, function, or null.

Events

Event Type	Description
`hide.bs.tooltip`	This event fires immediately when the `hide` instance method has been called.
`hidden.bs.tooltip`	This event fires when the tooltip has finished being hidden from the user (waiting for CSS transitions to complete).
`inserted.bs.tooltip`	This event fires after the `show.bs.tooltip` event, once the tooltip template has been added to the DOM.
`show.bs.tooltip`	This event fires immediately when the `show` instance method is called.
`shown.bs.tooltip`	This event fires when the tooltip has been made visible to the user (waiting for CSS transitions to complete).

Example event listener:

const myTooltipEl = document.getElementById('myTooltip')
const tooltip = hummingbird.Tooltip.getOrCreateInstance(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', () => {
  // do something...
})

tooltip.hide()

hummingbird

Getting Started

Customize

Layout & content

Forms

Components

Tooltips

Basic example

Directions

Custom tooltip

Disabled elements

CSS variables

Usage

Markup

Options

Data Attributes for Individual Tooltips

Methods

Events