See what's coming soon with Carbon V10-beta.

Skip to main content
Tooltips provide additional information upon hover or focus. They often contain helper text that is contextual to an element.

Tooltip

Tooltip label

This is some tooltip text. This box shows the maximum amount of text that should appear inside. If more room is needed please use a modal instead.

<!-- 
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<div id="tooltip-label" class="bx--tooltip__label" aria-describedby="unique-tooltip">
  Tooltip label
  <div tabindex="0" aria-labelledby="tooltip-label" data-tooltip-trigger data-tooltip-target="#unique-tooltip" role="tooltip" class="bx--tooltip__trigger">
      <svg width="16" height="16" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
        <g fill-rule="evenodd">
          <path d="M8 14.5a6.5 6.5 0 1 0 0-13 6.5 6.5 0 0 0 0 13zM8 16A8 8 0 1 1 8 0a8 8 0 0 1 0 16z" fill-rule="nonzero" />
          <path fill-rule="nonzero" d="M9 13H7V7h2z" />
          <circle cx="8" cy="4" r="1" />
        </g>
      </svg>
  </div>
</div>
<div id="unique-tooltip" data-floating-menu-direction="bottom" class="bx--tooltip" data-avoid-focus-on-open>
  <span class="bx--tooltip__caret"></span>
  <p>This is some tooltip text. This box shows the maximum amount of text that should appear inside. If more room is
    needed
    please use a modal instead.</p>
  <div class="bx--tooltip__footer">
    <a href="#" class="bx--link">Learn More</a>
    <button class="bx--btn bx--btn--primary" type="button">Create</button>
  </div>
</div>

Icon Tooltip

Vanilla JS

<!-- 
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<div class="bx--tooltip--icon">
  <button class="bx--tooltip__trigger bx--tooltip--icon__top" aria-label="Filter">
      <svg width="16" height="12" viewBox="0 0 16 12">
        <path d="M8.05 2a2.5 2.5 0 0 1 4.9 0H16v1h-3.05a2.5 2.5 0 0 1-4.9 0H0V2h8.05zm2.45 2a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3zM3.05 9a2.5 2.5 0 0 1 4.9 0H16v1H7.95a2.5 2.5 0 0 1-4.9 0H0V9h3.05zm2.45 2a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3z" />
      </svg>
  </button>
</div>

Definition Tooltip

Vanilla JS

<!-- 
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<div class="bx--tooltip--icon">
  <button class="bx--tooltip__trigger bx--tooltip--icon__top" aria-label="Filter">
      <svg width="16" height="12" viewBox="0 0 16 12">
        <path d="M8.05 2a2.5 2.5 0 0 1 4.9 0H16v1h-3.05a2.5 2.5 0 0 1-4.9 0H0V2h8.05zm2.45 2a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3zM3.05 9a2.5 2.5 0 0 1 4.9 0H16v1H7.95a2.5 2.5 0 0 1-4.9 0H0V9h3.05zm2.45 2a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3z" />
      </svg>
  </button>
</div>

Documentation

JavaScript (Applied only to click-to-open tooltip)

Getting component class reference

ES2015
import { Tooltip } from 'carbon-components';
With pre-build bundle (carbon-components.min.js)
var Tooltip = CarbonComponents.Tooltip;

Instantiating

// `#my-tooltip-trigger` is an element with `[data-tooltip-trigger]` attribute
Tooltip.create(document.getElementById('my-tooltip-trigger'));

Attributes

Name Param Description
data-tooltip-target Any unique CSS selector The selector, typically an id, to find the tooltip corresponding to the trigger.
data-tooltip-direction left, top, right, or bottom Setting this attribute overrides the directions set by this.options.tooltipDirection

Public Methods

Name Params Description
show Shows the tooltip.
hide Hides the tooltip.
release Deletes the instance and removes document event listeners.
Example - Showing tooltip
// `#my-tooltip-trigger` is an element with `[data-tooltip-trigger]` attribute
var tooltipInstance = Tooltip.create(document.getElementById('my-tooltip-trigger'));
tooltipInstance.show();

Options

Option Default Selector Description
selectorInit [data-tooltip-trigger] The CSS selector to find the tooltip.
objMenuOffset { top: 10, left: 0 } An object containing the top and left offset values in px
Example - Changing menu position by 8 pixels vertically
// `#my-tooltip-trigger` is an element with `[data-tooltip-trigger]` attribute
Tooltip.create(document.getElementById('my-tooltip-trigger'), {
  objMenuOffset(menuBody, direction) {
    const { objMenuOffset: offset } = Tooltip.options;
    const { top, left } = typeof offset !== 'function' ? offset : offset(menuBody, direction);
    return {
      top: top + 8,
      left,
    };
  },
});

Events

Event Name Description
'floating-menu-beingshown' The custom event fired before the menu gets open.
'floating-menu-shown' The custom event fired after the menu gets open.
'floating-menu-beinghidden' The custom event fired before the menu gets closed.
'floating-menu-hidden' The custom event fired after the menu gets closed.
Example - Preventing click-to-open tooltip from being closed in a certain condition
document.addEventListener('floating-menu-beinghidden', function(evt) {
  if (myApplication.shouldTooltipKeptOpen(evt.target)) {
    evt.preventDefault();
  }
});
Example - Notifying events of all click-to-open tooltips being hidden to an analytics library
document.addEventListener('floating-menu-hidden', function(evt) {
  myAnalyticsLibrary.send({
    action: 'Tooltip hidden',
    id: evt.target.id,
  });
});

Interactive tooltip

Selector Description
.bx--tooltip__trigger--bold Modifier class to make label bold.

HTML

By default, the tooltip (.bx--tooltip) goes right under <body>. You can change the behavior by adding data-floating-menu-container to one of the DOM ancestors of the tooltip's original location. For example, if you have HTML structure like below, the menu body will go under the second <div>:

<body>
  <div>
    <div data-floating-menu-container>
      <div>
        <div class="bx--tooltip__label" ...>
          Tooltip label
          <div tabindex="0" data-tooltip-trigger data-tooltip-target="#unique-tooltip" class="bx--tooltip__trigger" ...>...</div>
        </div>
        <div id="unique-tooltip" data-floating-menu-direction="bottom" class="bx--tooltip" ...>
          <span class="bx--tooltip__caret"></span> ...
        </div>
      </div>
    </div>
  </div>
</body>

Definition tooltip

This tooltip variation does not use any JavaScript and should be used to define a word. For anything more advanced please use the main variation.

Selector Description
.bx--tooltip--definition__top A simple tooltip that is displayed above the trigger.
.bx--tooltip--definition__bottom A simple tooltip that is displayed below the trigger.

Icon tooltip

This tooltip variation does not use any JavaScript and is good for short single line of text describing an icon. No label should be added to this variation.

Selector Description
.bx--tooltip--icon__top A simple tooltip that is displayed above the trigger.
.bx--tooltip--icon__bottom A simple tooltip that is displayed below the trigger.