Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 58 ยท Components

Dropdowns, Tooltips and Popovers

Create Bootstrap 5.3 dropdown menus, split buttons, tooltips and popovers, learn how Popper positions them, and enable the opt-in ones with JavaScript.

Three Bootstrap components share one idea: a small floating layer that appears next to another element. A dropdown is a menu of actions. A tooltip is a short label shown on hover or focus. A popover is a bigger bubble with a title and body text, shown on click. All three are positioned by a small library called Popper, which places the layer on the requested side and flips it if the page edge would cut it off.

Popper is already inside bootstrap.bundle.min.js, the script used in every example here. (If you load bootstrap.min.js alone, you would have to add Popper yourself, which is why the bundle is the simple choice; see Installing Bootstrap.) Dropdowns work from data attributes alone. Tooltips and popovers are opt-in: you must write one line of JavaScript for them, because they are costly to set up for every element automatically.

A dropdown has a wrapper, a toggle button and a menu. The wrapper (.dropdown) creates the positioning context. The button carries data-bs-toggle="dropdown". The menu is a list with the class dropdown-menu, and each entry is an <a> or <button> with dropdown-item.

A basic dropdown

The extra classes in the menu: dropdown-header labels a group, dropdown-divider draws a line, active highlights the current page, and disabled grays an item out. Use <a> for navigation and <button> for actions such as "Sign out" that run code. Keyboard users get arrow-key navigation, Escape to close, and Tab to leave, all built in.

Direction and alignment

The menu opens downward and aligned to the left edge by default. Change the direction by replacing dropdown on the wrapper (or the btn-group) with dropup, dropend or dropstart. To align the menu to the right edge of its button, add dropdown-menu-end to the menu. A responsive form such as dropdown-menu-lg-end aligns to the end only from the lg breakpoint upward.

You do not need to worry about overflow at the page edge: Popper notices when a menu would leave the viewport and flips it. The classes just set your preferred side.

Split buttons

A split button gives one primary action plus a menu of alternatives. It is a btn-group with two buttons: the action, and a second toggle with dropdown-toggle-split. The second button has no text, so add a visually-hidden label for screen readers.

Split button and directions

Closing behavior

A dropdown closes when you click outside, press Escape or click an item. The attribute data-bs-auto-close changes this on the toggle button:

Value The menu closes when
true (default) you click inside or outside
inside you click an item inside (outside clicks keep it open)
outside you click outside (clicks on items keep it open)
false only the toggle button is used

outside is the right choice for a menu containing checkboxes or a small form, where each click should not close the menu.

Tooltips

A tooltip shows a short hint when the pointer hovers over an element or when it receives keyboard focus. Add data-bs-toggle="tooltip" and the text in data-bs-title. Optionally choose a side with data-bs-placement (top, right, bottom or left).

Nothing happens until you create a Tooltip object for each element. The usual one-liner selects all of them:

JavaScript
document.querySelectorAll('[data-bs-toggle="tooltip"]')
  .forEach((element) => new bootstrap.Tooltip(element));
Enable tooltips

The last example shows a classic gotcha: a disabled button receives no pointer or focus events, so a tooltip placed on it never shows. The fix is to wrap it in a focusable element (tabindex="0", here a span) and attach the tooltip there.

Tooltips are for hints, not for essential information. Touch devices have no hover, and the text vanishes when the pointer leaves. Never hide something the visitor must read in a tooltip. Also give icon-only buttons a real aria-label; the tooltip text alone is not a reliable name.

Popovers

A popover is a tooltip with more room: a header and a body. It is also opt-in, uses the same pattern, and takes its text from data-bs-title and data-bs-content. It opens on click by default.

JavaScript
document.querySelectorAll('[data-bs-toggle="popover"]')
  .forEach((element) => new bootstrap.Popover(element));
A dismissible popover

The first popover stays until you click its button again. The second uses data-bs-trigger="focus", so it closes as soon as focus moves elsewhere; the element needs tabindex="0" (a real <button> is focusable already) and, on some browsers, a click on a link-like element must focus it.

Options as data attributes

Most options for tooltips and popovers can be written as data attributes, or passed in an object as the second argument to the constructor. The most useful ones:

Option Meaning
placement top, right, bottom, left, or auto
trigger hover, focus, click, or a mix such as hover focus
title / content the text to display
html allow HTML in the text (sanitized by Bootstrap)
delay milliseconds before showing or hiding
container an element to append the layer to, such as body
customClass extra classes for styling the bubble

With JavaScript options, the same tooltip looks like new bootstrap.Tooltip(el, { placement: 'bottom', delay: { show: 300, hide: 0 } }). Options in the object override data attributes.

flowchart LR
  A["Trigger element<br/>(button, link, span)"] -->|"hover, focus or click"| B["Bootstrap plugin"]
  B --> C["Popper<br/>computes position"]
  C --> D["Layer shown<br/>(menu, tooltip, popover)"]

Popper turns the trigger's position and the preferred side into coordinates, and flips the layer when there is no space.

Do not turn off the sanitizer lightly. When html: true is used, Bootstrap strips dangerous tags and attributes from the text. If your content contains user-written text, never disable that protection, and prefer plain text whenever the markup is not really needed.

More dropdown options

Direction classes cover most needs, but dropdowns have a few options for the cases they do not. Like the options above, each can be a data attribute (data-bs-offset="10,20") or a key in the object you pass to new bootstrap.Dropdown(el, { ... }).

Option Default What it does
offset [0, 2] moves the menu: [skidding, distance] in pixels (sideways along the toggle, then away from it)
boundary 'clippingParents' the element whose edges the menu must stay inside before it flips
reference 'toggle' the element the menu is placed against: 'toggle', 'parent', or an element
display 'dynamic' 'static' turns Popper off, so the menu keeps its CSS position (used inside navbars, where Bootstrap does this for you)
autoClose true true, 'inside', 'outside' or false (see "Closing behavior" above)
popperConfig null an object, or a function that receives Bootstrap's default Popper config and returns the one to use

reference: 'parent' is the useful one for split buttons. With a btn-group, the toggle is only the small arrow, so the menu lines up with the arrow. Setting data-bs-reference="parent" on the toggle places the menu against the whole group instead, so it starts at the left edge of the main button.

Offset, reference and popperConfig

Dark dropdowns

To get a dark menu on a light page, put data-bs-theme="dark" on the menu. Bootstrap 5.3 reads the color variables from the nearest theme attribute, so the menu, its items and the dividers all switch together. You will see older code with dropdown-menu-dark; it still works in 5.3, but it is deprecated and may be removed, so prefer the attribute. See dark mode for the full picture.

HTML
<ul class="dropdown-menu" data-bs-theme="dark">
  <li><a class="dropdown-item active" href="#">Active</a></li>
  <li><hr class="dropdown-divider"></li>
  <li><a class="dropdown-item" href="#">Separated link</a></li>
</ul>

More tooltip and popover options

Tooltips and popovers share a larger option list than the table above. The ones you will reach for after the basics:

Option Default What it does
fallbackPlacements ['top', 'right', 'bottom', 'left'] the sides to try, in order, when the preferred placement has no room (note the plural)
boundary 'clippingParents' the element the layer must stay inside
offset [0, 6] for tooltips, [0, 8] for popovers [skidding, distance], like the dropdown option
animation true fade the layer in and out
sanitize true clean HTML passed with html: true (turn this off only for content you fully control)
allowList a safe default list the tags and attributes the sanitizer keeps
sanitizeFn null your own function (for example, one backed by a library such as DOMPurify) that replaces the built-in sanitizer
template built-in markup the HTML used for the layer itself
selector false attach to elements added later, matched inside the trigger element (delegation)
popperConfig null an object, or a function receiving Bootstrap's default Popper config, for full control

fallbackPlacements and allowList are the ones that need an example. By default, the sanitizer keeps ordinary text markup (b, i, a, p, lists, headings and so on) but removes tags such as table, button and form, so those silently disappear from your popover. Add them to the allow-list on the constructor's Default object, once, before creating popovers:

Extending the sanitizer allow-list

The script tag is removed in both cases; the sanitizer always rejects scripts, event-handler attributes and javascript: URLs, and the allow-list only controls which harmless tags survive.

Extend the allow-list narrowly. Each tag you add widens what could be injected through your content. Never add script, iframe, style or attributes such as onclick, and never combine sanitize: false with text that comes from users. If you need rich HTML from outside sources, run it through a dedicated sanitizer library and pass that as sanitizeFn.

For positioning that the options above cannot express, popperConfig gives direct access to Popper. Passing a function keeps Bootstrap's own defaults and lets you change only what you need:

JavaScript
new bootstrap.Tooltip(el, {
  popperConfig(defaultConfig) {
    return {
      ...defaultConfig,
      modifiers: [
        ...defaultConfig.modifiers,
        { name: 'preventOverflow', options: { padding: 16 } }
      ]
    };
  }
});

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which of these components works from data attributes alone, with no JavaScript setup?

    Dropdowns initialize themselves from data-bs-toggle="dropdown". Tooltips and popovers are opt-in because of their cost and positioning work, so you create them with new bootstrap.Tooltip(...) or new bootstrap.Popover(...).
  2. 2. How do you build a split button?

    A split button is two buttons in a btn-group; the second one opens the menu. Give it a visually-hidden label for screen readers.
  3. 3. A tooltip on a disabled button never appears. What is the best fix?

    Disabled controls fire no pointer or focus events. A focusable wrapper can receive them.
  4. 4. Which setting keeps a dropdown open while the visitor ticks several checkboxes inside it?

    outside means the menu only closes on clicks outside it, so clicks on items inside keep it open.
  5. 5. What does Popper do for these components?

    Popper handles placement. Accessibility still needs your labels, roles and keyboard-friendly markup.

Summary

  • A dropdown is .dropdown + a data-bs-toggle="dropdown" button + .dropdown-menu of .dropdown-item entries; it needs no setup code.
  • dropup, dropend, dropstart, dropdown-menu-end and data-bs-auto-close control direction, alignment and closing.
  • A split button is a btn-group with an action button and a dropdown-toggle-split toggle.
  • Tooltips and popovers are opt-in: create them with new bootstrap.Tooltip(el) or new bootstrap.Popover(el).
  • Options come from data-bs-* attributes or a constructor object; wrap disabled controls in a focusable element.
  • Keep essential content out of tooltips and name icon buttons with aria-label.

Next lesson: Carousel, Offcanvas and Toasts.