# Bootstrap 5 Tooltips > Use Bootstrap Tooltips to add small, informative text boxes that appear when users hover or focus on an element. This feature enhances UX by providing contextual help without cluttering your interface. ## Overview Things to keep in mind when using the Bootstrap tooltip plugin: - Our Bootstrap tooltips depend on the third-party library [Popper](https://popper.js.org/) for positioning. You need to include [popper.min.js](https://cdn.jsdelivr.net/npm/@popperjs/core@2.11.8/dist/umd/popper.min.js) before `coreui.js` or use `coreui.bundle.min.js/coreui.bundle.js`, which includes Popper to ensure tooltips function correctly! - Tooltips are optional for performance reasons, so you need to initialize them yourself. - Bootstrap Tooltips with empty titles are never displayed. - Specify `container: 'body'` to prevent rendering issues in more complex components (such as our input groups, button groups, etc.). - Bootstrap tooltips cannot be triggered on hidden elements. - Tooltips for elements that are `.disabled` or `disabled` need to be activated on a wrapper element. - When triggered by hyperlinks that span multiple lines, tooltips will be centered. Use `white-space: nowrap;` on your `` elements to avoid this behavior. - Tooltips must be hidden before the related elements are removed from the DOM. - Our Bootstrap tooltips can be triggered thanks to an element inside a shadow DOM. Got all that? Awesome! Now, let's explore how they work through some examples. > By default, this component utilizes the built-in content sanitizer, which removes any HTML elements that are not explicitly allowed. Refer to the [sanitizer section in our JavaScript documentation](https://coreui.io/bootstrap/docs/getting-started/javascript/#sanitizer) for more details. > This component's animation effect relies on the `prefers-reduced-motion` media query. For more information, refer to the [reduced motion section of our accessibility documentation](https://coreui.io/bootstrap/docs/getting-started/accessibility/#reduced-motion). Got all that? Great, let's see how they work with some examples. ## Examples ### Enable Bootstrap tooltips You can enable tooltips using JavaScript or data attributes. Here's how to initialize all tooltip elements on a page: ```js const tooltipTriggerList = document.querySelectorAll('[data-coreui-toggle="tooltip"]') const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new coreui.Tooltip(tooltipTriggerEl)) ``` ### Tooltips on links Hover your cursor over the links below to see tooltips: > You can choose to use either `title` or `data-coreui-title` in your HTML. If you opt for `title,` Popper will automatically change it to `data-coreui-title` upon rendering the element. ### Custom tooltips _Added in 4.2.0._ Feel free to personalize the look of your tooltips with [CSS variables](#variables)! By setting a custom class using `data-coreui-custom-class="custom-tooltip"`, you can easily define your custom style and use it to adjust a local CSS variable. ```scss .custom-tooltip { --cui-tooltip-bg: var(--cui-primary); } ``` ```html ``` ### Positioning Bootstrap Tooltips support multiple placements: top, right, bottom, and left. The default is top. Directions are mirrored when using CoreUI in RTL. To change placement, use the `data-coreui-placement` attribute: ```html ``` ### Tooltips with HTML Content Bootstrap Tooltips support HTML content, allowing you to insert styled elements like ``, ``, or `` directly inside the tooltip. This feature is useful when you want to emphasize certain words, add inline formatting, or even insert icons. To enable this, set the `data-coreui-html="true"` attribute and include valid HTML in the title attribute. Be mindful of security when injecting dynamic content. ```html ``` This will render a styled tooltip that interprets the HTML tags instead of treating them as plain text. HTML tooltips are especially handy when you need richer formatting within a compact UI hint. ### Tooltips on SVG Elements Applying Bootstrap Tooltips to SVG elements requires a different approach, since SVGs do not support the `title` attribute in the same way HTML elements do. To show tooltips on SVG icons or shapes, you must initialize them manually using JavaScript. It’s recommended to set the container option to `'body'` to avoid positioning issues, especially when SVGs are nested inside complex layouts. ```html ``` Using Bootstrap Tooltips with SVGs is a great way to enhance accessibility and interactivity for icon-based UIs or data visualizations without modifying the structure of your SVGs. ## Usage The tooltip plugin creates content and markup as needed, and by default places tooltips following their trigger elements. Trigger the tooltip via JavaScript: ```js const exampleEl = document.getElementById('example') const tooltip = new coreui.Tooltip(exampleEl, options) ``` > ##### Overflow `auto` and `scroll` > > When a parent container has `overflow: auto` or `overflow: scroll`, such as with our `.table-responsive`, the tooltip position attempts to adjust automatically while maintaining its original placement. To fix this, set the boundary option in the flip modifier using the `popperConfig` option to any HTMLElement to replace the default value, `'clippingParents'`, like `document.body`: > > ```js > const tooltip = new coreui.Tooltip('#example', { > boundary: document.body // or document.querySelector('#boundary') > }) > ``` ### Markup The markup needed for a tooltip consists solely of a `data` attribute and a `title` on the HTML element you want to display a tooltip. The markup generated for a tooltip is quite simple, although it does require a position, which is set to `top` by default in the plugin. > ##### Making tooltips work for keyboard and assistive technology users > > Only add tooltips to HTML elements that are inherently keyboard-focusable and interactive, like links or form controls. While it is possible to make arbitrary HTML elements like ``s focusable by using the `tabindex="0"` attribute, doing so may create confusing tab stops on non-interactive elements for keyboard users. Moreover, most assistive technologies typically do not announce tooltips in these cases. Additionally, avoid depending solely on `hover` to trigger your tooltips, as this approach renders them inaccessible for keyboard users. ```html Hover over me ``` ### Disabled elements Elements that have the `disabled` attribute are non-interactive, which prevents users from focusing, hovering, or clicking on them to display a tooltip (or popover). To address this, consider triggering the tooltip from a surrounding `
` or ``, preferably making it keyboard-focusable by using `tabindex="0"`. ```html ``` ### Options Options can be passed using data attributes or JavaScript. To do this, append an option name to `data-coreui-`, such as `data-coreui-animation="{value}"`. Remember to convert the case of the option name from "_camelCase_" to "_kebab-case_" when using data attributes. For instance, you should write `data-coreui-custom-class="beautifier"` rather than `data-coreui-customClass="beautifier"`. Starting with CoreUI 4.2.6, all components support an **experimental** reserved data attribute named `data-coreui-config`, which can contain simple component configurations as a JSON string. If an element has attributes `data-coreui-config='{"delay":50, "title":689}'` and `data-coreui-title="Custom Title"`, then the final value for `title` will be `Custom Title`, as the standard data attributes will take precedence over values specified in `data-coreui-config`. Moreover, existing data attributes can also hold JSON values like `data-coreui-delay='{"show":50, "hide":250}'`. > Please note that for security reasons, the `sanitize`, `sanitizeFn`, and `allowList` options cannot be supplied via data attributes. | Name | Type | Default | Description | | --- | --- | --- | --- | | `allowList` | object | [Default value](https://coreui.io/bootstrap/docs/getting-started/javascript#sanitizer) | Defines the set of permitted HTML tags and attributes that can safely appear in the tooltip content when HTML rendering is enabled. This helps maintain control over the output and prevent injection of malicious code. | | `animation` | boolean | `true` | Determines whether the tooltip should fade in and out using a CSS transition. Set to `false` for instant show/hide behavior, which may be preferable for performance-sensitive interfaces. | | `container` | string, element, false | `false` | Specifies the parent container in which the tooltip should be inserted. Commonly used value is `'body'`, which helps avoid layout or overflow issues by ensuring the tooltip isn't clipped by parent elements. | | `delay` | number, object | `0` | Defines how long (in milliseconds) to wait before showing or hiding the tooltip. A single number applies to both actions, or you can provide an object like `{ show: 500, hide: 200 }` for separate control over each. | | `html` | boolean | `false` | Enables support for HTML content inside the tooltip. When set to `true`, the `title` attribute may include tags like ``, ``, or even icons. Be cautious with untrusted content as it increases XSS risk. | | `placement` | string, function | `'top'` | Sets the tooltip’s position relative to its target element. Valid values include `'top'`, `'bottom'`, `'left'`, `'right'`, or `'auto'`. You can also pass a function for dynamic placement based on element size or context. | | `selector` | string, false | `false` | Used to delegate tooltip activation to child elements within a container. This is particularly useful when you’re dynamically adding elements to the DOM that require tooltips. Note: the `title` attribute itself should not be used as a selector. | | `template` | string | `''` | Provides the HTML structure used to generate the tooltip. You can override it to include custom classes or elements. The `title` content is placed inside `.tooltip-inner`, and `.tooltip-arrow` is the visual pointer. | | `title` | string, element, function | `''` | The content displayed inside the tooltip. If a value is not provided, the component will fall back to the `title` attribute on the element. You can also provide a function that returns the content dynamically.| | `customClass` | string, function | `''` | Allows adding one or more custom CSS classes to the tooltip when it's rendered. Accepts a string with class names or a callback function that returns the class string. Useful for styling variants (e.g. light vs dark). | | `trigger` | string | `'hover focus'` | Determines which user interactions will cause the tooltip to show. Options include `click`, `hover`, `focus`, or `manual`. Multiple triggers can be combined using a space-separated string. Use `manual` for full programmatic control. | | `offset` | array, string, function | `[0, 6]` | Defines how far the tooltip should be offset from the target element. Use a string like `data-coreui-offset="10,20"` in attributes or pass a function to calculate the offset based on context. Popper.js modifiers are used under the hood. | | `fallbackPlacements` | string, array | `['top', 'right', 'bottom', 'left']` | Specifies alternative placements for the tooltip if the preferred one isn't feasible (e.g., due to lack of space). The tooltip will try these placements in order until one fits. For more information refer to Popper's [behavior docs](https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements). | | `boundary` | string, element | `'clippingParents'` | Determines the boundary within which the tooltip must remain visible. Can be a specific element or one of Popper’s keywords like `'viewport'` or `'window'`. This setting helps avoid unwanted clipping or overflow. For more information refer to Popper's [detectOverflow docs](https://popper.js.org/docs/v2/utils/detect-overflow/#boundary). | | `sanitize` | boolean | `true` | Controls whether HTML content in the tooltip should be sanitized before rendering. Strongly recommended to leave enabled unless you’re fully managing the content and trust its source. | | `allowList` | object | \[Default value]\(/getting-started/javascript/#sanitizer) | A detailed whitelist of tags and attributes considered safe when sanitization is enabled. This fine-tunes what HTML will be kept or stripped from the tooltip. | | `sanitizeFn` | null, function | `null` | You can define your own custom sanitization logic by passing a function here. Ideal if you want to use a specialized HTML sanitizer or integrate with existing security tools. If activated `'template'`, `'content'` and `'title'` options will be sanitized. | | `popperConfig` | null, object, function | `null` | Allows you to override or extend the default Popper.js configuration used by Bootstrap Tooltip. Can be an object or a function that receives the default config and returns a modified one, giving you full control over tooltip behavior and positioning logic. See [Popper's configuration](https://popper.js.org/docs/v2/constructors/#options).| > #### Data attributes for individual tooltips > > Options for individual tooltips can alternatively be specified through the use of data attributes, as explained above. #### Using function with `popperConfig` ```js const tooltip = new coreui.Tooltip(element, { popperConfig(defaultBsPopperConfig) { // const newPopperConfig = {...} // use defaultBsPopperConfig if needed... // return newPopperConfig } }) ``` ### Methods > #### Asynchronous methods and transitions > > All our API methods are **asynchronous** and initiate a **transition**. They return to the caller as soon as the transition begins but **before it concludes**. Furthermore, a method call on a **transitioning component will be ignored**. > > [Refer to our JavaScript documentation for further details](https://coreui.io/bootstrap/docs/getting-started/javascript/#asynchronous-functions-and-transitions). | Method | Description | | --- | --- | | `show` | Manually displays the Bootstrap tooltip linked to an element. This method is non-blocking—it returns immediately, even though the tooltip will appear shortly after. If the tooltip’s title is empty, nothing will be shown. **Returns to the caller before the tooltip has actually been shown** (i.e. before the `shown.coreui.tooltip` event occurs) | | `hide` | Hides the tooltip from view when triggered programmatically. Similar to `show`, this method is asynchronous and returns before the hiding animation finishes. **Returns to the caller before the tooltip has actually been hidden** (i.e. before the `hidden.coreui.tooltip` event occurs). | | `toggle` | Programmatically shows or hides a tooltip based on its current visibility state. Like `show` and `hide`, this method executes immediately and the visual change happens afterward. **Returns to the caller before the tooltip has actually been shown or hidden** (i.e. before the `shown.coreui.tooltip` or `hidden.coreui.tooltip` event occurs). | | `dispose` | Completely removes the tooltip instance from the target element. It clears event listeners and internal data. Tooltips created using delegation (e.g., via `selector`) cannot be destroyed on individual children. | | `enable` | Gives an element’s tooltip the ability to be shown. All tooltips are enabled by default unless manually disabled. | | `disable` | Disables the tooltip from being triggered. This includes both manual and automatic triggers until it's enabled again. | | `setContent` | Dynamically changes the content of an existing tooltip without reinitializing the instance. Useful for updating text based on user action or application state. | | `toggleEnabled` | Switches the ability for an element’s tooltip to be shown or hidden. | | `update` | Recalculates and repositions the tooltip, ensuring correct alignment if the DOM has changed (e.g., due to scroll, resize, or dynamic layout updates). | | `getInstance` | *Static* method that retrieves the current tooltip instance tied to a specific element. Returns `null` if the tooltip has not been initialized. | | `getOrCreateInstance` | *Static* method that either returns the existing tooltip instance or initializes a new one if none exists. Ensures consistent behavior in dynamic interfaces. | ```js const tooltip = coreui.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance // setContent example tooltip.setContent({ '.tooltip-inner': 'another title' }) ``` > The `setContent` method accepts an `object` argument, where each property-key is a valid `string` selector within the popover template, and each related property-value can be `string` | `element` | `function` | `null` ### Events | Event | Description | | --- | --- | | `show.coreui.tooltip` | Triggered right after the `show()` method is invoked. The tooltip is about to become visible, but hasn't been inserted into the DOM yet. You can use this event to perform actions before the tooltip is rendered. | | `shown.coreui.tooltip` | Fired after the tooltip is fully visible and any CSS transitions (like fade) have completed. Useful for tracking when the user can actually see the Bootstrap tooltip. | | `hide.coreui.tooltip` | Emitted immediately when the `hide()` method is called. At this point, the tooltip is still visible but is beginning the process of being hidden. | | `hidden.coreui.tooltip` | Dispatched once the tooltip has been fully removed from view and CSS transitions (if any) have finished. Ideal for cleanup logic or analytics. | | `inserted.coreui.tooltip` | Occurs after the tooltip has been injected into the DOM but before it becomes visible. This event gives you access to the generated tooltip element for advanced DOM manipulation. | ```js const myTooltipEl = document.getElementById('myTooltip') const tooltip = coreui.Tooltip.getOrCreateInstance(myTooltipEl) myTooltipEl.addEventListener('hidden.coreui.tooltip', () => { // do something... }) tooltip.hide() ``` ## Customizing ### CSS variables Bootstrap tooltips utilize local CSS variables on `.tooltip` for improved real-time customization. The values for the CSS variables are configured via Sass, ensuring that Sass customization is still supported as well. ```scss --cui-tooltip-zindex: #{$zindex-tooltip}; --cui-tooltip-max-width: #{$tooltip-max-width}; --cui-tooltip-padding-x: #{$tooltip-padding-x}; --cui-tooltip-padding-y: #{$tooltip-padding-y}; --cui-tooltip-margin: #{$tooltip-margin}; @include rfs($tooltip-font-size, --cui-tooltip-font-size); --cui-tooltip-color: #{$tooltip-color}; --cui-tooltip-bg: #{$tooltip-bg}; --cui-tooltip-border-radius: #{$tooltip-border-radius}; --cui-tooltip-opacity: #{$tooltip-opacity}; --cui-tooltip-arrow-width: #{$tooltip-arrow-width}; --cui-tooltip-arrow-height: #{$tooltip-arrow-height}; ``` ### SASS variables ```scss $tooltip-font-size: $font-size-sm !default; $tooltip-max-width: 200px !default; $tooltip-color: var(--cui-body-bg) !default; $tooltip-bg: var(--cui-emphasis-color) !default; $tooltip-border-radius: var(--cui-border-radius) !default; $tooltip-opacity: .9 !default; $tooltip-padding-y: $spacer * .25 !default; $tooltip-padding-x: $spacer * .5 !default; $tooltip-margin: null !default; // TODO: remove this in v6 $tooltip-arrow-width: .8rem !default; $tooltip-arrow-height: .4rem !default; // fusv-disable $tooltip-arrow-color: null !default; // Deprecated in 4.2.0 for CSS variables // fusv-enable ```