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> );}Shared delay provider
Section titled “Shared delay provider”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>;}Examples
Section titled “Examples”Hover or focus the trigger to reveal the hint.
import { Button } from "@nesra/ui/button";import { Tooltip } from "@nesra/ui/tooltip";import { Info } from "lucide-react";
export function TooltipBasicExample() { return ( <Tooltip content={ <span className="flex items-center gap-nesra-padding-md"> <Info aria-hidden="true" className="size-4" /> <span>Avg scaling</span> <span className="font-medium">+2%</span> </span> } render={<Button variant="outline" />} > Average scaling </Tooltip> );}Placements
Section titled “Placements”Basic Figma variants use top and bottom placement with start, center, or end alignment. Viewport collisions can change the rendered side or alignment.
import { Button } from "@nesra/ui/button";import { Tooltip, TooltipProvider } from "@nesra/ui/tooltip";
const sides = ["top", "bottom"] as const;const alignments = ["start", "center", "end"] as const;
export function TooltipPlacementsExample() { return ( <TooltipProvider delay={0}> <div className="grid grid-cols-3 gap-x-20 gap-y-16 p-12"> {sides.flatMap((side) => alignments.map((align) => ( <Tooltip align={align} content={`${side} ${align}`} key={`${side}-${align}`} render={<Button variant="outline" />} side={side} > {side} {align} </Tooltip> )), )} </div> </TooltipProvider> );}Multiple tooltips
Section titled “Multiple tooltips”TooltipProvider groups hover timing: after one tooltip opens, moving to another can skip the
initial delay during the provider’s 400ms timeout.
import { Button } from "@nesra/ui/button";import { Tooltip, TooltipProvider } from "@nesra/ui/tooltip";
export function TooltipMultipleExample() { return ( <TooltipProvider delay={600}> <div className="flex flex-wrap gap-nesra-spacing-md"> <Tooltip content="Revenue from completed orders" render={<Button variant="outline" />}> Revenue </Tooltip> <Tooltip content="Share of visitors who completed an order" render={<Button variant="outline" />} > Conversion </Tooltip> </div> </TooltipProvider> );}Long text and narrow layout
Section titled “Long text and narrow layout”The popup wraps long content. Its positioner uses 12px collision padding and may move the popup to keep it inside the viewport.
import { Button } from "@nesra/ui/button";import { Tooltip, TooltipProvider } from "@nesra/ui/tooltip";
const detail = "Average scaling increased over the previous period, even though the available space is narrow.";
export function TooltipOverflowExample() { return ( <TooltipProvider delay={0}> <div className="flex w-64 justify-between gap-nesra-spacing-md border border-nesra-stroke-border p-nesra-padding-md"> <Tooltip align="start" content={detail} render={<Button variant="outline" />} side="bottom"> Left edge </Tooltip> <Tooltip align="end" content={detail} render={<Button variant="outline" />} side="bottom"> Right edge </Tooltip> </div> </TooltipProvider> );}Delay control
Section titled “Delay control”delay and closeDelay are milliseconds for pointer hover. Keyboard focus discloses immediately.
import { Button } from "@nesra/ui/button";import { Tooltip } from "@nesra/ui/tooltip";
export function TooltipDelaysExample() { return ( <div className="flex flex-wrap gap-nesra-spacing-md"> <Tooltip content="Opens immediately" delay={0} render={<Button variant="outline" />}> Open immediately </Tooltip> <Tooltip content="Opens after 600ms" delay={600} render={<Button variant="outline" />}> Open after 600ms </Tooltip> <Tooltip closeDelay={1000} content="Stays open for 1s after pointer exit" delay={0} render={<Button variant="outline" />} > Close after 1s </Tooltip> </div> );}Custom non-interactive content
Section titled “Custom non-interactive content”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.
import { Tooltip } from "@nesra/ui/tooltip";
export function TooltipCustomExample() { return ( <Tooltip content={ <> <div className="border-b border-nesra-stroke-inverse p-nesra-padding-xl type-nesra-body-small-medium text-nesra-text-inverse"> 03 Aug 2026 </div> <div className="space-y-2 p-nesra-padding-xl"> <div className="flex justify-between"> <span>Spend</span> <span>2x</span> </div> <div className="border-t border-nesra-stroke-inverse pt-2 font-medium">METRICS</div> <div className="flex items-center justify-between"> <span className="flex items-center gap-2"> <span aria-hidden="true" className="size-2.5 bg-nesra-categorical-blue-base" /> Revenue </span> <span>2x</span> </div> <div className="flex items-center justify-between"> <span className="flex items-center gap-2"> <span aria-hidden="true" className="size-2.5 bg-nesra-categorical-violet-base" /> Conversion </span> <span>2x</span> </div> <div className="flex items-center justify-between"> <span className="flex items-center gap-2"> <span aria-hidden="true" className="size-2.5 bg-nesra-categorical-orange-base" /> Orders </span> <span>2x</span> </div> </div> </> } popupClassName="w-[327px] rounded-nesra-xl p-0" side="bottom" > 03 Aug 2026 metrics </Tooltip> );}Rich Tooltip
Section titled “Rich Tooltip”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> );}Title, description, and decoration
Section titled “Title, description, and decoration”Wrap a term in <strong> to emphasize it in Body/Small/Semibold.
import { Button } from "@nesra/ui/button";import { RichTooltip } from "@nesra/ui/tooltip";
export function RichTooltipExample() { return ( <RichTooltip description={ <> Audiences in the <strong>Awareness</strong> stage viewed brand-related ads, UGC, brand content or livestreams a limited number of times in the past 15 days. </> } render={<Button variant="outline" />} title="Awareness audience" > Awareness audience </RichTooltip> );}Without title or decoration
Section titled “Without title or decoration”Omit title for one-line definitions. decoration={false} removes the tint and sparkles.
import { Button } from "@nesra/ui/button";import { RichTooltip } from "@nesra/ui/tooltip";import { Info } from "lucide-react";
export function RichTooltipMinimalExample() { return ( <RichTooltip decoration={false} description="Spend divided by the number of conversions in the selected range." render={<Button aria-label="Cost per conversion" size="icon-md" variant="ghost" />} side="bottom" > <Info aria-hidden="true" className="size-4" /> </RichTooltip> );}Placements
Section titled “Placements”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
Section titled “Tooltip Trigger”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> );}Sizes and tones
Section titled “Sizes and tones”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.
import { TooltipTrigger } from "@nesra/ui/tooltip";
const definition = ( <> Audiences in the <strong>Awareness</strong> stage viewed brand-related ads, UGC, brand content or livestreams a limited number of times in the past 15 days. </>);
export function TooltipTriggerExample() { return ( <div className="flex flex-wrap items-end gap-8"> <TooltipTrigger description={definition} title="Awareness audience"> Awareness </TooltipTrigger> <TooltipTrigger description={definition} title="Awareness audience" tone="muted"> Awareness </TooltipTrigger> <TooltipTrigger description={definition} size="xs" title="Awareness audience"> Awareness </TooltipTrigger> <TooltipTrigger description={definition} size="xs" title="Awareness audience" tone="muted"> Awareness </TooltipTrigger> </div> );}Inline in text
Section titled “Inline in text”The trigger is an inline <button>, so it can sit inside a sentence and wraps across lines.
import { TooltipTrigger } from "@nesra/ui/tooltip";
export function TooltipTriggerInlineExample() { return ( <p className="m-0 max-w-md type-nesra-body-xsmall-regular text-nesra-text-body"> Grow your{" "} <TooltipTrigger description="People who saw your brand a few times in the past 15 days but have not engaged yet." size="xs" > awareness audience </TooltipTrigger>{" "} before you retarget it with conversion campaigns. </p> );}Light and Dark
Section titled “Light and Dark”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.
Accessibility
Section titled “Accessibility”- 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-describedbylinks 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 disabledprevents disclosure. To hint a natively disabled control, pass a focusable wrapper throughrenderso 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
descriptiontext, even while the popup is closed. The open popup hasrole="dialog", is named bytitle, and is described bydescription. - The trigger’s accessible name comes from
children. Icon-only triggers passed throughrenderneed anaria-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.
API reference
Section titled “API reference”Tooltip
Section titled “Tooltip”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.
TooltipProvider
Section titled “TooltipProvider”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. |
RichTooltip
Section titled “RichTooltip”| 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
Section titled “TooltipTrigger”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.