Fixing Bootstrap Tooltip not loading issues

Introduction

Bootstrap is a great CSS framework to get started. However, sometimes I find myself getting the tooltip to work correctly. This ranges from not loading at all to random quirks with browsers.

We will go over a few tips/ checklist on fixing any tooltip issues with Bootstrap.

There are a few reasons why your tooltip from Boostrap is not working correctly, this includes:

• Not referencing the Bootstrap Javascript library,
• Check for the correct version of Bootstrap used - the tooltip feature is different across versions
• Check that we have enabled the tooltip in Javascript or via HTML data attributes
• Check that we are using tooltips correctly (and understand limitations)

Fix 1 - Correct reference to Bootstrap CSS and Bootstrap JS

For tooltips to work with Bootstrap, you will need to include both Bootstrap CSS and Bootstrap JS.

If you do not want to bloat your site with unnessary JavaScript, then you can import Popper.JS (https://popper.js.org/) - this is the library that Bootstrap tooltips use under the hood.

So for Bootstrap 4 we can have the following references:

<!-- THE CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@4.0.0/dist/css/bootstrap.min.css" integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">

<!-- THE JAVASCRIPT -->
<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js" integrity="sha384-KJ3o2DKtIkvYIK3UENzmM7KCkRr/rE9/Qpg6aAZGJwFDMVNA/GpGFF93hXpG5KkN" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/popper.js@1.12.9/dist/umd/popper.min.js" integrity="sha384-ApNbgh9B+Y1QKtv3Rn7W3mgPxhU9K/ScQsAP7hUibX39j7fakFPskvXusvfa0b4Q" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@4.0.0/dist/js/bootstrap.min.js" integrity="sha384-JZR6Spejh4U02d8jOt6vLEHfe/JQGiRRSQQxSfFWpi1MquVdAyjUar5+76PVCmYl" crossorigin="anonymous"></script>

As for Bootstrap version 5, it should look something like this:

<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7MsXsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>

The above, we just use the Bootstrap JS bundle that is provided.

Fix 2 - Check for the correct version of Bootstrap used!

Using Bootstrap Tooltip is different across Bootstrap version 4 and Bootstrap version 5 and lately version 5.2.

The main differences are the expected HTML data attributes, and initialization without jQuery (since Bootstrap 5 is moving away from jQuery and just using vanila JavaScript).

Bootstrap 5 breaking changes:

• Dropped jQuery.
• Upgraded from Popper v1.x to Popper v2.x.

So for Bootstrap version 4, for the HTML, it requires the following data attributes:

• data-toggle="tooltip"
• title="...."
• data-placement="top"

Now with Bootstrap version 5, to setup the HTML we now need to use the HTML data attributes with a data-bs- prefix:

• data-bs-toggle="tooltip"
• title="Tooltip on top"
• data-bs-placement="top"

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Tooltip on top">
  Tooltip on top
</button>

Other breaking changes with Bootstrap version 5:

• Renamed .arrow to .tooltip-arrow in our default tooltip template.
• The default value for the fallbackPlacements is changed to [‘top’, ‘right’, ‘bottom’, ‘left’] for better placement of popper elements.
• Renamed whiteList option to allowList.

Fix 3 - Check that we have enabled the tooltip in Javascript and correct HTML data attributes

To enable tooltips, there are two ways to do this. Adding the Bootstrap JS wont automattically intialize, we need to enable them ourselves. This is by design from the Bootstrap team to improve performance.

For version 4 of Bootstrap, our HTML structure will look like the following (keep note of the data-toggle="tooltip" HTML attribute):

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">
  Tooltip on top
</button>

And then in our Javascript we can use the following to enable tooltips.

$(function () {
  $('[data-toggle="tooltip"]').tooltip()
})

Now for version 5 of Bootstrap, the authors have scrapped jQuery, so the JavaScript used to initialize it is just vanila JavaScript

const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl))

For version 5.2, we can use the following JavaScript (notice the new bootstrap.Tooltip namespace instead of jQuery):

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

Note: Keep note of the HTML attributes

Bootstrap verion 4 uses the data attributes of data-toggle=...

For version 5 of Bootstrap, the data attribute used is data-bs-toggle=...

Now for version 5.2, there is even another further update on the title. With previous versions, we only need to specify the title= attribute to define the tool tip content. With version 5.2, we now need to use data-bs-title=...

Going a bit further with configuration over code, in version 5.2 of bootstrap, they now let you store configuration options using JSON in your data attributes.

As of Bootstrap 5.2.0, all components support an experimental reserved data attribute data-bs-config that can house simple component configuration as a JSON string.

For example, you can now do data-bs-config='{"delay":0, "title":123}'.

Keep in mind overwritting other tooltip settings though!

Fix 4 - Check that we are using tooltips correctly

Common issues with Tooltip can arise when we are not using Tooltip correctly or not aware of its quirks. Just make sure that we keep the following in mind:

• Tooltips that do not have any text in their title attribute will not be shown.
• To prevent issues with displaying tooltips within complex components such as input groups and button groups, use the “container: ‘body’” option.
• Attempting to activate tooltips on elements that are not visible/hidden will not have any effect.
• To enable tooltips on elements that are .disabled (or disabled=true), it must be triggered on the parent wrapper element.

As an example, in the below, we want a tooltip on the button, but it is disabled! So to get the tooltip to work, we need to target the outer <span> element:

<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="Disabled tooltip">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

Tip: Keep in mind accessibility

To ensure that tooltips are accessible for users of keyboard and assistive technology, it is important to only add them to HTML elements that are typically able to be focused on and interacted with using a keyboard, such as links or form controls.

Avoid using the tabindex='0' attribute to make other elements, such as <span>s, focusable, as this can be confusing and disruptive for keyboard users, and most assistive technologies are not able to announce the tooltips in this context. Furthermore, it is important to consider not just hover as the trigger for tooltips as it would make it impossible to access the tooltips using keyboard alone.

Summary

In this post we went over a few ways to fix issues with Bootstrap Tooltip not working correctly.

We want to make sure that you have included the Bootstrap CSS and JavaScript files in your project. The tooltip functionality is part of the Bootstrap JavaScript library, so it will not work without it.

We need to consider the version of Bootstrap Tooltip that we are using. A common issue is when we are trying to implement something that is in version 5 but using version 4 HTML attributes. Boostrap version 4 we can still use jQuery and HTML data attribute of data-toggle="tooltip". However with version 5 and 5.2, data attributes now have a prefix of data-bs- (eg this becomes data-bs-toggle="tooltop")

Finally we need to be aware of the limitations of Tooltips - it does not work with empty title attributes, needs to be enabled in Javascript, disabled elements need to trigger tooltip JS on the parent element not itself!