Tooltips
Custom replacement for browser tooltips—themed with CSS variables and positioned by Idea React’s OverlayBox.
Overview
Hover the button below to see a tooltip. By default, the tooltip will appear above their trigger element (the child of OverlayBox).
<OverlayBox title="Tooltip on top">
<Button
theme="secondary"
variant="solid"
>
Hover me
</Button>
</OverlayBox>Things to know when using tooltips with OverlayBox:
- Provide a non-empty
titleso the tooltip has a meaningful accessible description. - 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
disabledelements must be triggered on a wrapper element. - When triggered from links whose text spans multiple lines, tooltips will be centered. Use
white-space: nowrapin the link's styles to avoid this behavior. - Unmount
OverlayBoxtogether with its trigger so the tooltip and positioning listeners are cleaned up. - 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.
Pass rich content as React nodes instead of injecting untrusted HTML. React escapes text content by default.
The animation effect of this component is dependent on the prefers-reduced-motion media query.
Examples
Tooltips on links
Hover over the links below to see tooltips:
Placeholder text to demonstrate some inline links with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of real text. And all that to give you an idea of how tooltips would look when used in real-world situations. So hopefully you’ve now seen how these tooltips on links can work in practice, once you use them on your own site or project.
<p className="text-body-secondary">
Placeholder text to demonstrate some{' '}
<OverlayBox title="Default tooltip">
<a href="#tooltips-on-links">
inline links
</a>
</OverlayBox>
with tooltips. This is now just filler, no killer. Content placed here just to mimic the
presence of
<OverlayBox title="Another tooltip">
<a href="#tooltips-on-links">
real text
</a>
</OverlayBox>
. And all that to give you an idea of how tooltips would look when used in real-world
situations. So hopefully you’ve now seen how
<OverlayBox title="Another one here too">
<a href="#tooltips-on-links">
these tooltips on links
</a>
</OverlayBox>
{' '}can work in practice, once you use them on{' '}
<OverlayBox title="The last tip!">
<a href="#tooltips-on-links">
your own
</a>
</OverlayBox>
{' '}site or project.
</p>Use the title prop on OverlayBox, rather than the native title attribute on the trigger, to avoid duplicate browser tooltips.
Custom tooltips
You can customize the appearance of tooltips using CSS variables. We pass a CSS module class through overlayClassName to scope our custom appearance and use it to override a local CSS variable.
<OverlayBox
overlayClassName="_tooltip_1wmlc_9"
title="This top tooltip is themed via CSS variables."
>
<Button
theme="secondary"
variant="solid"
>
Custom tooltip
</Button>
</OverlayBox>Placement
Set 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.
<div className="d-flex flex-wrap gap-3">
<OverlayBox
placement="top"
title="Tooltip on top"
>
<Button
theme="secondary"
variant="solid"
>
Tooltip on top
</Button>
</OverlayBox>
<OverlayBox
placement="right"
title="Tooltip on right"
>
<Button
theme="secondary"
variant="solid"
>
Tooltip on right
</Button>
</OverlayBox>
<OverlayBox
placement="bottom"
title="Tooltip on bottom"
>
<Button
theme="secondary"
variant="solid"
>
Tooltip on bottom
</Button>
</OverlayBox>
<OverlayBox
placement="left"
title="Tooltip on left"
>
<Button
theme="secondary"
variant="solid"
>
Tooltip on left
</Button>
</OverlayBox>
</div>Responsive placement
Change placement at different breakpoints using responsivePlacement={{ md: 'right', lg: 'bottom' }}, where each breakpoint is one of sm, md, lg, xl, or 2xl.
<div className="d-flex flex-wrap gap-3">
<OverlayBox
placement="top"
responsivePlacement={{
lg: 'bottom',
md: 'right'
}}
title="Responsive tooltip"
>
<Button
theme="secondary"
variant="solid"
>
Top → md:right → lg:bottom
</Button>
</OverlayBox>
<OverlayBox
placement="left"
responsivePlacement={{
lg: 'top'
}}
title="Responsive tooltip"
>
<Button
theme="secondary"
variant="solid"
>
Left → lg:top
</Button>
</OverlayBox>
</div>Resize your browser to see the tooltip placement change at different breakpoints.
Custom HTML
And with custom HTML added:
<OverlayBox title={<><em>Tooltip</em>{' '}<u>with</u>{' '}<b>HTML</b></>}>
<Button
theme="secondary"
variant="solid"
>
Tooltip with HTML
</Button>
</OverlayBox>With an icon (rendered through Icon):
<OverlayBox title={<><Icon name="heart-fill" />{' '}Tooltip with an icon</>}>
<Button
theme="secondary"
variant="solid"
>
Tooltip with icon
</Button>
</OverlayBox>Interactive tooltips
Move the pointer onto the tip to reach interactive content inside it, such as a link. The tooltip stays open while the pointer is over the trigger or the tip. It hides when the pointer leaves both, or when you press the Escape key. This helps satisfy the WCAG 1.4.13 “Content on Hover or Focus” success criterion.
<OverlayBox title={<>Need more details?{' '}<a href="#interactive-tooltips">Read the documentation</a>.</>}>
<Button
theme="secondary"
variant="solid"
>
Interactive tooltip
</Button>
</OverlayBox>Disabled elements
Disabled controls are not interactive, so users cannot focus, hover, or click them to trigger a tooltip. As a workaround, place the control inside a keyboard-focusable wrapper and use that wrapper as the OverlayBox trigger.
<OverlayBox title="Disabled tooltip">
<span
className="d-inline-block rounded-3"
tabIndex={0}
>
<Button
disabled
theme="primary"
variant="solid"
>
Disabled button
</Button>
</span>
</OverlayBox>CSS
Variables
Local CSS custom properties expose the component’s colors, spacing, borders, and transitions. Override them through style or a CSS module. The defaults below come from the Bootstrap stylesheet used by Idea React; see the upstream variable reference.
| Variable | Default |
|---|---|
--bs-tooltip-zindex | var(--bs-z-tooltip) |
--bs-tooltip-max-width | 200px |
--bs-tooltip-padding-x | var(--bs-spacer-3) |
--bs-tooltip-padding-y | calc(var(--bs-spacer) * 0.375) |
--bs-tooltip-font-size | var(--bs-font-size-sm) |
--bs-tooltip-color | var(--bs-bg-body) |
--bs-tooltip-bg | var(--bs-fg-body) |
--bs-tooltip-border-radius | var(--bs-radius-5) |
--bs-tooltip-opacity | 0.95 |
--bs-tooltip-arrow-width | 0.8rem |
--bs-tooltip-arrow-height | 0.4rem |
--bs-tooltip-transition-property | opacity |
--bs-tooltip-transition-duration | 0.15s |
--bs-tooltip-transition-timing | linear |
Usage
Delegated tooltips
To enable tooltips on many triggers at once—including elements added to the DOM later—render an OverlayBox for each trigger in your React list. React mounts and removes the overlays with their triggers; no selector-based plugin initialization is needed.
<div className="d-flex flex-wrap gap-3">
<OverlayBox title="First tooltip">
<Button
theme="secondary"
variant="solid"
>
First trigger
</Button>
</OverlayBox>
<OverlayBox title="Second tooltip">
<Button
theme="secondary"
variant="solid"
>
Second trigger
</Button>
</OverlayBox>
<OverlayBox title="Third tooltip">
<Button
theme="secondary"
variant="solid"
>
Third trigger
</Button>
</OverlayBox>
</div>Markup
Wrap the trigger in OverlayBox and provide its title. It renders the Tooltip markup, places it relative to the trigger, and connects it with aria-describedby.
Keep tooltips accessible to keyboard and assistive technology users by only adding them to HTML elements that are traditionally keyboard-focusable and interactive (such as links or form controls). While other HTML elements can be made focusable by adding tabIndex={0}, this can create annoying and confusing tab stops on non-interactive elements for keyboard users, and most assistive technologies currently do not announce tooltips in this situation. Additionally, do not rely solely on hover as the trigger for your tooltips as this will make them impossible to trigger for keyboard users.
A shown tooltip can be dismissed by pressing the Escape key, helping satisfy the WCAG 1.4.13 “Content on Hover or Focus” success criterion. The tooltip also stays open while the pointer moves onto the tip, so users can reach interactive content inside it. As with dropdown menus, a tooltip shown inside a dialog is dismissed on its own: the first Escape closes the tooltip and a subsequent one closes the dialog.
Options
OverlayBox prop | Default | Description |
|---|---|---|
title | required | Tooltip text or rich React content. |
trigger | hover and focus | Choose "click", "hover", "focus", or a combination as an array. |
placement | "top" | Preferred direction: top, right, bottom, or left. |
responsivePlacement | — | Override direction at named breakpoints. |
container | alongside trigger | A selector, DOM element, or callback returning an element. |
delay | 0 | Show/hide delay in milliseconds, or { show: 500, hide: 100 }. |
offset | 8 | Distance from the trigger, or a [crossAxis, mainAxis] pair. |
padding | 8 | Viewport inset for overflow avoidance. |
flip | true | Flip direction when space is constrained. |
overlayClassName | — | Apply a CSS module class to the tooltip. |