Skip to content

Tooltip

⋯

Tooltip shows a non-interactive hint on hover or focus. Its popup uses the inverse surface and text roles, so it is dark in Light and light in Dark. content accepts text or a non-interactive React composition.

The page also covers two definition parts. Rich Tooltip is a popover-surface definition with an optional title and a blue decoration. Tooltip Trigger is an inline term with a dashed underline that opens a Rich Tooltip.

Import Tooltip from @nesra/ui/tooltip or the package root. content is the popup and children is the trigger label. render uses an existing control as the trigger.

import { Button } from "@nesra/ui/button";
import { Tooltip } from "@nesra/ui/tooltip";
export function SaveHint() {
return (
<Tooltip content="Save changes" render={<Button variant="outline" />}>
Save
</Tooltip>
);
}

TooltipProvider is optional. Place it once around an app or layout when nearby tooltips should skip the opening delay after the first one. Tooltips without a provider still open on hover and focus.

import { TooltipProvider } from "@nesra/ui/tooltip";
import type { ReactNode } from "react";
export function AppProviders({ children }: { children: ReactNode }) {
return <TooltipProvider>{children}</TooltipProvider>;
}

Hover or focus the trigger to reveal the hint.

Basic Figma variants use top and bottom placement with start, center, or end alignment. Viewport collisions can change the rendered side or alignment.

TooltipProvider groups hover timing: after one tooltip opens, moving to another can skip the initial delay during the provider’s 400ms timeout.

The popup wraps long content. Its positioner uses 12px collision padding and may move the popup to keep it inside the viewport.

delay and closeDelay are milliseconds for pointer hover. Keyboard focus discloses immediately.

Pass text and metric rows through content. Use popupClassName to change the popup’s padding and shape. Use Popover for links, buttons, inputs, or any content users must interact with.

Rich Tooltip shows a definition with an optional title, a multi-line description, and a decoration of a blue tint and sparkles. It opens on hover, keyboard focus, and press, including a tap on touch screens.

import { Button } from "@nesra/ui/button";
import { RichTooltip } from "@nesra/ui/tooltip";
export function AudienceDefinition() {
return (
<RichTooltip
description="Audiences who viewed brand content a limited number of times."
render={<Button variant="outline" />}
title="Awareness audience"
>
Awareness audience
</RichTooltip>
);
}

Wrap a term in <strong> to emphasize it in Body/Small/Semibold.

Omit title for one-line definitions. decoration={false} removes the tint and sparkles.

The Figma Variant names the arrow side, so it is the opposite of side.

Figma side align
Variant=Bottom, Position=Left "top" "start"
Variant=Bottom, Position=Center "top" "center"
Variant=Bottom, Position=Right "top" "end"
Variant=Top, Position=Left "bottom" "start"
Variant=Top, Position=Center "bottom" "center"
Variant=Top, Position=Right "bottom" "end"

The arrow points at the trigger’s center. Viewport collisions can change the rendered side or alignment.

Tooltip Trigger marks a term with a dashed underline and opens its definition in a Rich Tooltip. Hover and the open state turn the text and underline blue.

import { TooltipTrigger } from "@nesra/ui/tooltip";
export function AwarenessTerm() {
return (
<TooltipTrigger
description="Audiences who viewed brand content a limited number of times."
title="Awareness audience"
>
Awareness
</TooltipTrigger>
);
}

md uses Body/Medium/Semibold for titles and xs uses Body/XSmall/Regular for meta labels. default uses text-headline and muted uses text-support.

The trigger is an inline <button>, so it can sit inside a sentence and wraps across lines.

Grow your before you retarget it with conversion campaigns.

The tooltip uses the Figma inverse roles, so it contrasts with the page in both modes: dark in Light and light in Dark.

Part Token Light Dark
Popup and arrow --nesra-foundation-bg-inverse (Foundation/bg-inverse) gray-950 gray-50
Text --nesra-text-inverse (Text/text-inverse) white gray-950
Icons (currentColor) inherit text-inverse; use --nesra-icon-inverse directly white gray-950
Dividers in content --nesra-stroke-inverse (Stroke/stroke-inverse) gray-800 gray-200

The arrow uses the popup color in both modes. Figma lists the Dark arrow as an open item, so this may change when the design team settles it. Custom content should use the inverse roles above instead of static-white or primitive grays, which do not switch with the theme.

Rich Tooltip and Tooltip Trigger use the popover surface roles, so they follow the page theme.

Part Token Light Dark
Rich Tooltip popup and arrow --nesra-surface-popover-bg-neutral (Surface/popover-bg-neutral) white gray-900
Rich Tooltip border --nesra-stroke-border (Stroke/stroke-border) gray-200 gray-800
Rich Tooltip title --nesra-text-headline (Text/text-headline) gray-900 white
Rich Tooltip description --nesra-text-body (Text/text-body) gray-900 white
Decoration tint (top to 60%) --nesra-categorical-blue-subtle to --nesra-surface-popover-bg-neutral blue-50 blue-950
Decoration sparkles (20%) --nesra-icon-info (Icon/icon-info) blue-500 blue-500
Rich Tooltip shadow shadow-nesra-lg (Box Shadow/shadow-lg) — —
Term, default tone --nesra-text-headline (Text/text-headline) gray-900 white
Term, muted tone --nesra-text-support (Text/text-support) gray-500 gray-400
Term underline --nesra-stroke-border-strong (Stroke/stroke-border-strong) gray-300 gray-700
Term hover and open text --nesra-text-link (Text/text-link) blue-600 blue-400
Term hover and open underline --nesra-stroke-link (Stroke/stroke-link) blue-500 blue-500

The Figma Rich Tooltip description says it always renders Light, but the component does not pin a variable mode. Nesra UI follows the bound roles, so Rich Tooltip is dark in Dark. This may change when the design team settles the open question.

  • The trigger opens the same popup on keyboard focus and pointer hover. Escape, blur, pointer exit, and disabling the root dismiss it without moving focus into the popup.
  • The popup has role="tooltip". aria-describedby links the trigger to the popup when it is mounted. The trigger still needs a clear accessible name. Keep essential information visible in the page. Touch users cannot depend on hover.
  • Tooltip disabled prevents disclosure. To hint a natively disabled control, pass a focusable wrapper through render so the hint remains available to keyboard users.
  • There is no entrance or exit animation. Reduced-motion users see the same immediate state change.

Rich Tooltip and Tooltip Trigger use Base UI Popover with openOnHover, because Base UI disables Tooltip on touch screens and a definition must stay reachable there.

  • Hover opens the popup after delay. Keyboard focus opens it immediately. A click or tap toggles it.
  • Focus stays on the trigger while the popup is open. Escape, blur, an outside press, and pointer exit close it.
  • Enter and Space toggle the popup while the trigger is focused.
  • The trigger’s accessible description is always the description text, even while the popup is closed. The open popup has role="dialog", is named by title, and is described by description.
  • The trigger’s accessible name comes from children. Icon-only triggers passed through render need an aria-label.
  • Keep content non-interactive. Focus never moves into the popup, so keyboard users cannot reach links or buttons placed there. Use Popover for interactive content.

The common API composes the trigger, portal, positioner, popup, and arrow.

Prop Type Default Effect
content ReactNode Required Non-interactive popup content.
children ReactNode — Trigger label or content.
render Base UI render prop <button> Uses an existing control as the trigger.
side "top" | "bottom" | "left" | "right" "top" Preferred popup side.
align "start" | "center" | "end" "center" Preferred popup alignment.
delay number (ms) 600ms Hover open delay.
closeDelay number (ms) 0ms Hover close delay.
container HTMLElement | ShadowRoot | ref document.body Portal target.
className string | state callback — Trigger classes.
popupClassName string — Popup classes, including Custom layout overrides.

Root props such as open, defaultOpen, onOpenChange, and disabled are also forwarded.

Shares hover timing across tooltips in one app or layout. TooltipProvider forwards Base UI Tooltip Provider props, including children.

Prop Type Default Effect
delay number (ms) 600ms effective Time before opening on hover.
closeDelay number (ms) 0ms Time before closing after pointer exit.
timeout number (ms) 400ms Window in which another tooltip opens immediately.
Prop Type Default Effect
description ReactNode Required Definition text and the trigger’s description.
title ReactNode — Heading that names the popup.
decoration boolean true Shows the blue tint and sparkles.
children ReactNode — Trigger label or content.
render Base UI render prop <button> Uses an existing control as the trigger.
side "top" | "bottom" | "left" | "right" "top" Preferred popup side.
align "start" | "center" | "end" "center" Preferred popup alignment.
delay number (ms) 300ms Hover open delay.
closeDelay number (ms) 0ms Hover close delay.
open boolean — Controlled open state.
defaultOpen boolean false Initial open state when uncontrolled.
onOpenChange (open, eventDetails) => void — Base UI Popover open change callback.
container HTMLElement | ShadowRoot | ref document.body Portal target.
className string | state callback — Trigger classes.
popupClassName string — Popup classes. The default popup width is 320px.

The trigger also forwards its ref. Keyboard focus opens report eventDetails.reason as "imperative-action".

TooltipTrigger accepts every RichTooltip prop except render, plus these props.

Prop Type Default Effect
size "md" | "xs" "md" Body/Medium/Semibold or Body/XSmall/Regular.
tone "default" | "muted" "default" text-headline or text-support text.
className string — Trigger classes.

The trigger renders a <button type="button"> and forwards its ref.

See colors, typography, and shape and elevation for the underlying tokens.