Tooltip

import { Tooltip } from "@/ui";

Tooltip wraps MUI's Tooltip in Petavue styling: a dark box with 12px white text that fades in over 180ms. Use it to name an icon-only control, to explain a control whose label cannot say everything, or to show text that has been cut short.

UsageCopy Anchor Link

Wrap one element and give the text in title. Pass describeChild so the element keeps its own name and the tooltip is read as extra description.

<Tooltip title="Pull the latest numbers from HubSpot and Google Ads" describeChild>
  <Button variant="secondaryGhost" label="Refresh data" icon={ArrowsClockwise} />
</Tooltip>

The child must accept a ref and pass on the event props it receives. Button, native elements and anything built with forwardRef do. A plain function component that drops unknown props does not, and the tooltip will never open.

Icon-only buttonsCopy Anchor Link

Give the button an aria-label and pass describeChild. A child's own aria-label always takes priority over the tooltip, and with describeChild the tooltip text is never used as the name, so the tooltip can later say more than the label without renaming the button.

<Tooltip title="Delete page" describeChild>
  <Button variant="secondaryGhost" icon={Trash} aria-label="Delete page" />
</Tooltip>

When the tooltip is the nameCopy Anchor Link

Without describeChild, a text title is copied onto the child as its aria-label, unless the child passes an aria-label of its own. That is fine for an icon-only button with no label, where the tooltip text is the name.

<Tooltip title="Download as CSV">
  <Button variant="secondaryGhost" icon={DownloadSimple} />
</Tooltip>

Any control with visible text needs describeChild. An aria-label overrides visible text, so without it "Refresh data" above would be announced as "Pull the latest numbers from HubSpot and Google Ads".

PlacementCopy Anchor Link

The default is bottom. Use top for most controls in the product so the tooltip does not cover what comes next. left and right suit narrow rails. Add arrow when the tooltip could be read as belonging to a neighbouring control. MUI flips the tooltip to the other side if there is no room.

<Tooltip title="Opens above" placement="top">…</Tooltip>
<Tooltip title="Opens below" placement="bottom">…</Tooltip>
<Tooltip title="Opens to the left" placement="left">…</Tooltip>
<Tooltip title="Opens to the right" placement="right">…</Tooltip>
<Tooltip title="With an arrow" placement="top" arrow>…</Tooltip>

Text that is cut shortCopy Anchor Link

With displayTooltipOnOverflow, the tooltip only opens when its child is actually truncated. Hover both names: only the long one opens. The child must be the element that has the ellipsis, because that is the one measured. A ResizeObserver re-checks when the width changes.

<Tooltip title={campaign.name} displayTooltipOnOverflow placement="top">
  <span className="block truncate max-w-[200px]">{campaign.name}</span>
</Tooltip>

Rich contentCopy Anchor Link

title can be any element, such as a small legend. Keep it to a few lines. Raise or lower the width cap with maxWidth. If people need to click inside it, use a popover instead.

<Tooltip title={<SyncStatusLegend />} arrow placement="top" maxWidth="260px" describeChild>
  <span tabIndex={0} aria-label="What the sync colours mean"><Info size={16} /></span>
</Tooltip>

On a disabled controlCopy Anchor Link

A disabled button does not fire the events the tooltip listens for, and MUI logs an error if you wrap one directly. Wrap it in a focusable <span> and put the tooltip on that. This is the right place to say why the action is not available.

<Tooltip title="Connect a domain before you publish" placement="top">
  <span className="inline-flex" tabIndex={0}>
    <Button variant="primary" label="Publish page" disabled />
  </span>
</Tooltip>

LookCopy Anchor Link

The colours are hard-coded in Tooltip.jsx rather than read from the tokens. They match the tokens named above.

PropsCopy Anchor Link

Any other prop (enterDelay, leaveDelay, onOpen, onClose, followCursor and so on) is passed to MUI's Tooltip.

AccessibilityCopy Anchor Link

• The tooltip opens on mouse hover after 100ms, on keyboard focus, and on a long press on touch screens. It closes when the pointer or focus leaves, and on Escape.
• The tooltip itself has role="tooltip".
• Do not put anything people need to read only in a tooltip. Touch users rarely see it. Put essential information on the page.
• Use describeChild whenever the child has visible text or a label of its own. See the table above.
• Make the child focusable. A tooltip on a plain <span> or icon needs tabIndex={0} and an aria-label, or keyboard users never see it.

Do and don'tCopy Anchor Link

• Do keep tooltip text short: a name, or one sentence.
• Do use a tooltip to say why a control is disabled.
• Do use displayTooltipOnOverflow for names that may be cut short in tables and cards.
• Don't put links, buttons or form fields inside a tooltip. It closes as the pointer moves towards them.
• Don't repeat the visible label in the tooltip. "Refresh data" does not need a tooltip saying "Refresh data".
• Don't restyle it with styles. Every tooltip in the product should look the same.