Tooltips

Overview

Hover the button below to see a tooltip. By default, the tooltip will appear above their trigger element (anything with the data-bs-toggle="tooltip" attribute).

<button type="button" class="btn btn-solid theme-primary"
        data-bs-toggle="tooltip"
        data-bs-title="Tooltip on top">
  Example tooltip
</button>

Things to know when using the tooltip plugin:

• Tooltips rely on the third party library Floating UI for positioning. You must include floating-ui.dom.umd.min.js before bootstrap.js, or use one bootstrap.bundle.min.js which contains Floating UI.
• Tooltips are automatically initialized when using data-bs-toggle="tooltip".
• Tooltips with zero-length titles are never displayed.
• Specify container: 'body' to avoid rendering problems in more complex components (like our input groups, button groups, etc).
• Triggering tooltips on hidden elements will not work.
• Tooltips for .disabled or disabled elements must be triggered on a wrapper element.
• When triggered from hyperlinks that span multiple lines, tooltips will be centered. Use white-space: nowrap; on your <a>s to avoid this behavior.
• Tooltips must be hidden before their corresponding elements have been removed from the DOM.
• Tooltips can be triggered thanks to an element inside a shadow DOM.

Got all that? Great, let’s see how they work with some examples.

Examples

Tooltips on links

Hover over the links below to see tooltips:

<p class="fg-3">Placeholder text to demonstrate some <a href="#" data-bs-toggle="tooltip" data-bs-title="Default tooltip">inline links</a> with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of <a href="#" data-bs-toggle="tooltip" data-bs-title="Another tooltip">real text</a>. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you’ve now seen how <a href="#" data-bs-toggle="tooltip" data-bs-title="Another one here too">these tooltips on links</a> can work in practice, once you use them on <a href="#" data-bs-toggle="tooltip" data-bs-title="The last tip!">your own</a> site or project.</p>

Custom tooltips

You can customize the appearance of tooltips using CSS variables. We set a custom class with data-bs-custom-class="custom-tooltip" to scope our custom appearance and use it to override a local CSS variable.

.custom-tooltip {
  --bs-tooltip-bg: var(--bd-violet-bg);
  --bs-tooltip-color: var(--bs-white);
}

<button type="button" class="btn btn-solid theme-secondary"
        data-bs-toggle="tooltip" data-bs-placement="top"
        data-bs-custom-class="custom-tooltip"
        data-bs-title="This top tooltip is themed via CSS variables.">
  Custom tooltip
</button>

Placement

Set data-bs-placement to change the direction. Hover over the buttons below to see the four tooltips directions: top, right, bottom, and left. Directions are mirrored when using Bootstrap in RTL.

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

Responsive placement

Change placement at different breakpoints using responsive prefixes. The syntax is breakpoint:placement, where breakpoint is one of sm, md, lg, xl, or 2xl.

<button type="button" class="btn btn-solid theme-secondary"
        data-bs-toggle="tooltip"
        data-bs-placement="top md:right lg:bottom"
        data-bs-title="Responsive tooltip">
  Top → md:right → lg:bottom
</button>
<button type="button" class="btn btn-solid theme-secondary"
        data-bs-toggle="tooltip"
        data-bs-placement="left lg:top"
        data-bs-title="Responsive tooltip">
  Left → lg:top
</button>

Resize your browser to see the tooltip placement change at different breakpoints.

Custom HTML

And with custom HTML added:

<button type="button" class="btn btn-solid theme-secondary"
        data-bs-toggle="tooltip"
        data-bs-html="true"
        data-bs-title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

With an SVG:

<a href="#" class="d-inline-block"
        data-bs-toggle="tooltip"
        data-bs-title="Default tooltip"
        aria-label="Hover or focus to see default tooltip">
  <svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 100 100" aria-hidden="true">
    <rect width="100%" height="100%" fill="#563d7c"/>
    <circle cx="50" cy="50" r="30" fill="#007bff"/>
  </svg>
</a>

Disabled elements

Elements with the disabled attribute aren’t interactive, meaning users cannot focus, hover, or click them to trigger a tooltip (or popover). As a workaround, you’ll want to trigger the tooltip from a wrapper <div> or <span>, ideally made keyboard-focusable using tabindex="0".

<span class="d-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

Tooltips use local CSS variables on .tooltip for real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

--tooltip-zindex: #{$zindex-tooltip};
--tooltip-max-width: #{$tooltip-max-width};
--tooltip-padding-x: #{$tooltip-padding-x};
--tooltip-padding-y: #{$tooltip-padding-y};
--tooltip-font-size: #{$tooltip-font-size};
--tooltip-color: #{$tooltip-color};
--tooltip-bg: #{$tooltip-bg};
--tooltip-border-radius: #{$tooltip-border-radius};
--tooltip-opacity: #{$tooltip-opacity};
--tooltip-arrow-width: #{$tooltip-arrow-width};
--tooltip-arrow-height: #{$tooltip-arrow-height};

Sass variables

$tooltip-font-size:                 var(--font-size-sm);
$tooltip-max-width:                 200px;
$tooltip-color:                     var(--bg-body);
$tooltip-bg:                        var(--fg-body);
$tooltip-border-radius:             var(--border-radius);
$tooltip-opacity:                   .95;
$tooltip-padding-y:                 $spacer * .375;
$tooltip-padding-x:                 $spacer * .75;

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;

Usage

The tooltip plugin generates content and markup on demand, and by default places tooltips after their trigger element. Trigger the tooltip via JavaScript:

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

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

Markup

The required markup for a tooltip is only a data attribute and title on the HTML element you wish to have a tooltip. The generated markup of a tooltip is rather simple, though it does require a position (by default, set to top by the plugin).

<!-- 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>

Dependencies

The tooltip plugin requires the following JavaScript files if you're building Bootstrap's JS from source:

Options

As options can be passed via data attributes or JavaScript, you can append an option name to data-bs-, as in data-bs-animation="{value}". Make sure to change the case type of the option name from “camelCase” to “kebab-case” when passing the options via data attributes. For example, use data-bs-custom-class="beautifier" instead of data-bs-customClass="beautifier".

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. When an element has data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456 and the separate data attributes will override values given on data-bs-config. In addition, existing data attributes are able to house JSON values like data-bs-delay='{"show":0,"hide":150}'.

The final configuration object is the merged result of data-bs-config, data-bs-, and js object where the latest given key-value overrides the others.

Using function with floatingConfig

const tooltip = new bootstrap.Tooltip(element, {
  floatingConfig(defaultBsFloatingConfig) {
    // const newFloatingConfig = {...}
    // use defaultBsFloatingConfig if needed...
    // return newFloatingConfig
  }
})

Methods

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

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

Events

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

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

tooltip.hide()