bootstrap_ref_js_tooltip

Bootstrap 5 JavaScript Tooltips

Tooltips are small pop-up boxes that appear when a user hovers over or focuses on an element, providing contextual information. Bootstrap 5 tooltips are powered by Popper.js and require JavaScript initialization.

Key change: Bootstrap 5 no longer depends on jQuery. All JavaScript plugins, including tooltips, are implemented in vanilla JavaScript.

Enabling Tooltips via data-bs-* Attributes

The easiest way to add a tooltip is using data-bs-* attributes directly in your HTML. data-bs-toggle="tooltip" activates the tooltip.

The title attribute (or data-bs-title for HTML content) specifies the text to be displayed inside the tooltip.

<button type="button" class="btn btn-secondary"
        data-bs-toggle="tooltip" data-bs-placement="top"
        title="This is a tooltip!">
  Hover over me
</button>

<!--
  Remember: Tooltips must be initialized via JavaScript for them to work, even when using data attributes.
  See the 'Via JavaScript' section below.
-->

Initializing Tooltips Via JavaScript

Tooltips must be explicitly initialized. You can select elements with data-bs-toggle="tooltip" and initialize them.

// Initialize all tooltips on a page
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'));
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new bootstrap.Tooltip(tooltipTriggerEl);
});

// Initialize a single tooltip by its ID
var myTooltipEl = document.getElementById('mySpecialTooltip');
if (myTooltipEl) {
  var tooltip = new bootstrap.Tooltip(myTooltipEl, {
    // Optional configuration object
    boundary: 'window' // Example option
  });
}

/*
  Common Pitfall: Forgetting to include this initialization script is the most common reason tooltips don't appear.
  Ensure this script runs after the DOM is loaded and after Bootstrap's JS is included.
  For more details: https://getbootstrap.com/docs/5.3/components/tooltips/#enable-tooltips
*/

Tooltip Options

Options can be passed via data-bs-* attributes or JavaScript. For data attributes, append the option name to data-bs-, like data-bs-placement="left" or data-bs-html="true".

Name	Type	Default	Description
animation	boolean	true	Apply a CSS fade transition to the tooltip.
container	string | false | Element	false	Appends the tooltip to a specific element. Example: container: 'body' or data-bs-container="body". Useful for avoiding rendering issues in complex components.
delay	number | object	0	Delay showing and hiding the tooltip (ms). Object structure: delay: { "show": 500, "hide": 100 }. Can be set via data-bs-delay="500" (for both) or data-bs-delay='{"show":500,"hide":100}'.
html	boolean	false	Allow HTML markup within the tooltip. If true, use data-bs-title instead of the title attribute for the HTML content. Example: data-bs-html="true" data-bs-title="<em>HTML</em> **here**". Security Note: Sanitize user input if using this option to prevent XSS attacks.
placement	string | function	’top’	How to position the tooltip: auto, top, bottom, left, right. Can also be a function.
selector	string | false	false	If a selector is provided, tooltip objects will be delegated to the specified targets. Useful for dynamically added content.
template	string	(Default SVG arrow template)	Base HTML to use when creating the tooltip. The tooltip’s title will be injected into .tooltip-inner. The .tooltip-arrow will be the arrow.
title	string | Element | function	”	Default title value if title attribute or data-bs-title is not present. Can be a function for dynamic titles.
offset	[number, number] | string | function	[0, 0]	Offset of the tooltip relative to its target. Example: data-bs-offset="10,20".
trigger	string	’hover focus’	How tooltip is triggered: click, hover, focus, manual. You can pass multiple triggers separated by a space. Example: data-bs-trigger="click focus".

For a full list of options and their detailed explanations, visit the official documentation: https://getbootstrap.com/docs/5.3/components/tooltips/#options

Tooltip Methods

Tooltip instances provide methods to control their behavior programmatically.

Method	Description
bootstrap.Tooltip.getInstance(element)	Static method to get the tooltip instance associated with a DOM element.
bootstrap.Tooltip.getOrCreateInstance(element, [config])	Static method to get the tooltip instance associated with a DOM element, or create a new one if it wasn’t initialized.
show()	Reveals an element’s tooltip. myTooltip.show()
hide()	Hides an element’s tooltip. myTooltip.hide()
toggle()	Toggles an element’s tooltip. myTooltip.toggle()
dispose()	Hides and destroys an element’s tooltip. myTooltip.dispose()
enable()	Gives an element’s tooltip the ability to be shown. myTooltip.enable()
disable()	Removes the ability for an element’s tooltip to be shown. myTooltip.disable()
toggleEnabled()	Toggles the ability for an element’s tooltip to be shown or hidden. myTooltip.toggleEnabled()
update()	Updates the position of an element’s tooltip. myTooltip.update()

Example of using a method:

var myButton = document.getElementById('myButtonWithTooltip');
var tooltipInstance = bootstrap.Tooltip.getInstance(myButton);
// or to create if it doesn't exist:
// var tooltipInstance = bootstrap.Tooltip.getOrCreateInstance(myButton);

// To show the tooltip programmatically:
// tooltipInstance.show();

Tooltip Events

Bootstrap tooltips expose several events that you can hook into.

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

Example of listening to an event:

var myTooltipEl = document.getElementById('exampleTooltip');
if (myTooltipEl) {
  myTooltipEl.addEventListener('shown.bs.tooltip', function () {
    console.log('Tooltip is now fully shown!');
  });
}

Customizing Tooltip Appearance with CSS

You can customize the look of tooltips using CSS by targeting Bootstrap’s tooltip classes or by using CSS custom properties (variables). Bootstrap 5 makes extensive use of CSS variables for easier customization.

/* Example: Customizing tooltip background and text color using CSS variables */
:root {
  --bs-tooltip-bg: #8AC007;
  --bs-tooltip-color: #FFFFFF;
  --bs-tooltip-opacity: 0.95;
  --bs-tooltip-arrow-width: .9rem;
  --bs-tooltip-arrow-height: .45rem;
  --bs-tooltip-padding-x: 1rem;
  --bs-tooltip-padding-y: .5rem;
  --bs-tooltip-font-size: .9rem;
}

/* For more specific overrides if needed: */
.tooltip-inner {
  /* Overrides Bootstrap's default if variables are not enough */
  background-color: #007bff; /* Example: Blue background */
  color: white;
  border-radius: .25rem;
  padding: .5rem 1rem;
}

.tooltip-arrow::before {
  /* Example: Changing arrow color to match custom background */
  /* border-top-color: #007bff; /* If tooltip is on top */
}

/*
  Best Practice: Start by overriding CSS custom properties.
  Refer to Bootstrap's _variables.scss (or the compiled CSS) to see all available tooltip CSS variables.
  Find them here: https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss (search for 'tooltip')
*/

Application Scenario: Tooltips are excellent for providing hints about icon buttons, explaining abbreviations, or showing full text for truncated content.