Advanced Ant UI Kit & Design System

Documentation

Introduction Get Started Theming Tokens Roadmap Changelog llms.txt

Components

Charts

X AI

Kiosk

Usage

When to reach for Tooltip, what each of its axes is for, and the decisions it leaves to you.

When to use

A tooltip is a short hint that appears on hover or focus and disappears again. It names a control that shows no word of its own, or it adds one line the control had no room for. A reader only sees it by pointing at or focusing the control, so nothing in it can be required.

Naming an icon-only button in a toolbar, usually with its keyboard shortcut beside the word.
Spelling out a truncated cell, a timestamp given as “3d ago”, or an abbreviation in a table header.
Saying why a control is unavailable, so a disabled button is not a dead end.
Explaining a glyph whose meaning is conventional but not universal: a status dot, a sync icon, a lock.

What to use instead. Two neighbors cover most of what a tooltip gets stretched into.

Popover when the content is interactive. A button, a link or a field inside a hover bubble means the reader has to keep the pointer on a moving path to reach it, and a keyboard reader cannot reach it at all. Popover is built for a panel you enter.
A visible label whenever the control has room for one. A word on the button is readable on touch, in a screenshot, and without a pointer. A tooltip is what you fall back to when the space is not there.
Helper text under a field for anything the reader needs while typing, and Alert or a form error for anything they must act on.

Placement

placement takes twelve values and defaults to top: the four sides (top, bottom, left, right) and eight corner variants (topLeft, topRight, bottomLeft, bottomRight, leftTop, leftBottom, rightTop, rightBottom).

Placement is a preference. With autoAdjustOverflow, on by default, a bubble that would be clipped opens on the other side. Do not build a layout that only works at one placement.
The bubble renders into document.body and is themed there, so set getPopupContainer only when it has to scroll or clip with its trigger, like inside a scrolling panel. In a box with overflow set to hidden, auto or scroll, the bubble then flips at the box's edge instead of the viewport's.
Keep one side per surface. A row of toolbar buttons where each hint picks its own side reads as noise, and the reader loses the place their eye was going to.
arrow accepts { pointAtCenter: true }, which only changes anything on the six corner placements. By default the arrow sits near the bubble's edge. With pointAtCenter, it sits over the middle of the trigger.

Trigger

trigger defaults to ["hover", "focus"] and also takes click and contextMenu, or an array of them.

Keep the default trigger. A single value replaces both, so trigger="hover" hides the hint from keyboard users. Pass an array like ["click", "focus"] to add a trigger and keep focus.
Use trigger="click" for interactive content. A button or link inside a hover bubble is hard to reach before the bubble closes. For anything more than a hint, use Popover.
Tooltip adds no element around its child. It attaches to the child, so the trigger keeps its own layout, and a className on Tooltip styles the popup.
A custom component has to forward its ref and spread the props it receives. Plain text is wrapped in a <span> for you.

What belongs in the title

title is the content, and it takes a node or a function. overlay is the older name for the same slot and is kept for compatibility. Write title.

One line, ideally a few words. The bubble is at most 250px wide (the maxWidth token) and wraps past it, so a paragraph becomes a block of text floating over the thing it is about.
Nothing the reader has to have belongs in here. It is invisible on touch, absent from a printed page, and gone the moment the pointer moves. Terms, prices, errors and legal copy go on the page.
An empty or null title turns the tooltip off. Use it to make a tooltip conditional instead of mounting and unmounting it. A title of 0 still shows.
A function title runs each time the bubble opens, so use it for content that has to be fresh, like the current time.
Rich content is allowed and sometimes right: an avatar, a name, a file's metadata. Keep it read-only. A card with a link in it wants Popover and a click trigger.

Delays and motion

mouseEnterDelay and mouseLeaveDelay are both 0.1 by default, in seconds, not milliseconds. The enter delay stops a row of icons flashing bubbles as the pointer crosses it. The leave delay lets the pointer cross a small gap without the bubble vanishing.

Raise the enter delay on a dense grid where the pointer is often passing through. Lower it in a toolbar, where the reader aims at each button.
transition={false} removes the open and close animation. Set mouseEnterDelay and mouseLeaveDelay to 0 as well for hints that appear at once, like on an icon toolbar. The motion prop can change the animation but not remove it.
For a dense toolbar, add size="small" and arrow={false} to the two above.
Share one bubble with UniqueProvider. Tooltips inside it use a single bubble that slides from trigger to trigger. The kit does not re-export it, so import Tooltip.UniqueProvider from antd.

Color, size and shape

color takes a preset name, which follows the theme, or any CSS color, which does not. Without it, the bubble is colorBgSpotlight with colorTextLightSolid text.

Color a bubble only when the color means something (a destructive action, a warning) and keep that meaning the same everywhere. A hint tinted for decoration reads as a status the reader then has to decode.
Presets keep white text, so bright ones like yellow and gold are hard to read. The Accessibility tab has the details.
medium is the default and already compact. It has less padding and smaller type than Ant Design's bubble, and it follows compact mode. Use small in dense toolbars, where it steps the type down one more size.
Pair a shape with arrow={false} or a center placement. round is a pill and squircle has superellipse corners. The arrow does not follow the curve, so on a corner placement a curved bubble pulls away from it. Browsers without corner-shape show squircle with the default corners.
Turning the arrow off adds a border in light mode. The thin border keeps an arrowless bubble apart from the page, whether arrow={false} comes from the tooltip or from ConfigProvider.

Styling it

Style the bubble with classNames. It takes root, container and arrow, or a function that returns them, and your classes win over the kit's. The bubble is a portal, so a selector written on the trigger never reaches it.
Set the width with max-w-96. With the kit's tokens, max-w-sm to max-w-xl are spacing steps, so max-w-md is 20px wide. Use max-w-96 or a rem value like max-w-[20rem].
Dim text inside the bubble with opacity. The bubble has its own background, so page colors like text-secondary can disappear on it. opacity-70 works on any bubble color.

When a tooltip is the wrong answer

On touch there is no hover. A tap either does the thing or does nothing, so a hover-only hint is absent for a large share of readers. If the information matters on a phone, put it on the page.
A tooltip is never a control's only accessible name. It is linked with aria-describedby, and only while the bubble is open. See the Accessibility tab.
A disabled button needs a <span> for a click trigger. A disabled button fires no click, so a trigger="click" tooltip on it never opens. Wrap it in a <span> and put pointer-events-none on the button. Hover works without the span.
Do not put a tooltip on something that already says the same word. A hint repeating the visible label is a bubble covering the page for no gain.
Do not stack one on a control that also opens a menu, a dialog or a Popover on the same gesture. Two overlays racing the same pointer flicker.
Do not use one for a validation error. It is transient, it is positioned over other content, and the reader cannot go back and read it again.