Tooltip
A tooltip is a small text label that appears when a user hovers over or focuses on an element, such as an icon button that needs a short explanation. Bootstrap 5 provides styled tooltips positioned by the Popper library. Unlike most Bootstrap components, tooltips are opt-in: adding the data attribute is not enough, you must also start them with a line of JavaScript.
Marking up a tooltip
Put data-bs-toggle="tooltip" on the element and the text in data-bs-title. The older title attribute also works, and Bootstrap moves its value into the tooltip so the browser's own grey tooltip does not appear as well. Use data-bs-placement to choose top, bottom, left or right.
<button type="button" class="btn btn-outline-secondary"
data-bs-toggle="tooltip"
data-bs-placement="bottom"
data-bs-title="Copy link to clipboard">
Copy
</button>
<script src="bootstrap.bundle.min.js"></script>
<script>
document.querySelectorAll('[data-bs-toggle="tooltip"]')
.forEach(el => new bootstrap.Tooltip(el));
</script>
Why the initialisation step exists
Tooltips listen for mouse and focus events and calculate their position every time they open, which costs a little work. Bootstrap leaves that choice to you so pages with hundreds of elements do not pay for tooltips they never use. The snippet above finds every element marked for a tooltip and creates an instance for each one. Run it after the elements exist in the page, for example at the end of body or after you insert new content.
Options worth knowing
| Option | What it changes |
|---|---|
placement | Preferred side; Popper flips it if there is no room |
trigger | Events that show it, default "hover focus" |
html | Allows HTML inside the tooltip text (sanitised by default) |
delay | Milliseconds before showing or hiding |
customClass | Extra class for your own styling |
Options can be passed as data attributes, such as data-bs-delay='{"show":300,"hide":100}', or as an object in the constructor. Instances also expose show(), hide(), toggle(), setContent() and dispose().
Pitfalls that catch beginners
The first is loading bootstrap.min.js without Popper. Tooltips need Popper for positioning, and the simplest fix is to load bootstrap.bundle.min.js, which includes it. The second is putting a tooltip on a disabled button. Disabled elements do not fire mouse events, so the tooltip never opens; wrap the button in a span with tabindex="0" and attach the tooltip to the wrapper instead.
A third issue appears in single-page apps: if you remove an element while its tooltip is open, the floating label can stay stuck on screen. Call dispose() on the instance before removing the element.
Tooltips added after the page loads, for example rows inserted by a fetch call, will not have instances yet. Either run the initialisation code again for the new elements, or pass a selector option to a tooltip created on a parent element so it handles matching children automatically.
Using tooltips responsibly
Touch screens have no hover, so a tooltip should only add a hint, never hold information a user needs to complete a task. Keep the text to a few words, make sure the trigger element can receive keyboard focus, and give icon-only buttons an aria-label as well.
Ready to master real-world web development?
Learn HTML, CSS3, Bootstrap and JavaScript hands-on with mentor-led sessions.