Tooltip

Client componentEngine: react-aria

ImportCopy Anchor Link

import { Tooltip } from '@nizivo/react/tooltip';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/kbd.css
import '@nizivo/react/css/tooltip.css';

Static or interactiveCopy Anchor Link

Client. It always ships React Aria's tooltip and overlay code (+19,625 B gzip under Turbopack for one Tooltip on the Next.js fixture), once per page however many tooltips it has. Information a user needs belongs in visible text; for an icon-only action, IconButton pairs the tooltip for you. How to choose.

The triggerCopy Anchor Link

Compose a Button into the trigger; it is still the recommended look:

<Tooltip.Trigger render={<Button variant="tertiary">Export</Button>} />

For an icon-only action, use an IconButton: it pairs itself with a Tooltip that shows its label, so it needs no Tooltip.Root.

A bare <Tooltip.Trigger> is a plain, unstyled <button>, but it has a minimum size of its own: at least 24 by 24 CSS pixels around a short text or a single glyph, the minimum target of WCAG 2.2 success criterion 2.5.8 (Target Size, Minimum), so two side by side still meet it. It also carries nz-hit-target, so under a coarse pointer it gets the same 44 px hit area as every standalone pressable. A trigger you render yourself through render keeps its own size and gets neither.

A trigger inside running text, such as a word in a sentence that shows a tooltip, is the exception: render your own element through render there. The 24 px minimum would make its line taller than the others, and under a coarse pointer the 44 px hit area would reach into the lines above and below and take taps meant for a link there. WCAG 2.2 2.5.8 exempts a target inside a sentence, so the inline element needs neither.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Button } from '@nizivo/react/button';
import { Tooltip } from '@nizivo/react/tooltip';

export function TooltipExample(): JSX.Element {
  return (
    <Tooltip.Root>
      <Tooltip.Trigger render={<Button variant="tertiary">Export</Button>} />
      <Tooltip.Popup side="end">Download the report as CSV</Tooltip.Popup>
    </Tooltip.Root>
  );
}

import type { JSX } from 'react';
import { Button } from '@nizivo/react/button';
import { Tooltip } from '@nizivo/react/tooltip';

export function TooltipShortcutExample(): JSX.Element {
  return (
    <Tooltip.Root content="Export the report" shortcut="mod+e">
      <Tooltip.Trigger render={<Button variant="secondary">Export</Button>} />
    </Tooltip.Root>
  );
}

import type { JSX } from 'react';
import { Button } from '@nizivo/react/button';
import { Tooltip } from '@nizivo/react/tooltip';

export function TooltipOpenExample(): JSX.Element {
  return (
    <Tooltip.Root defaultOpen delay={0}>
      <Tooltip.Trigger render={<Button variant="secondary">Refresh</Button>} />
      <Tooltip.Popup>Refresh data</Tooltip.Popup>
    </Tooltip.Root>
  );
}

Other exportsCopy Anchor Link

TooltipLabels type

import type { TooltipLabels } from '@nizivo/react/tooltip'

Strings the engine renders (§9.3 rule 7): React Aria's Tooltip renders none.

type TooltipLabels = Record<string, never>

TooltipPopupProps type

import type { TooltipPopupProps } from '@nizivo/react/tooltip'

The props of Tooltip.Popup, listed above.

TooltipPopupState type

import type { TooltipPopupState } from '@nizivo/react/tooltip'

Name	Type	Default	Description
enteringrequired	boolean	–
exitingrequired	boolean	–
siderequired	Side "top" | "right" | "bottom" | "left"	–

TooltipRootProps type

import type { TooltipRootProps } from '@nizivo/react/tooltip'

The props of Tooltip.Root, listed above.

TooltipSide type

import type { TooltipSide } from '@nizivo/react/tooltip'

Logical side; the resolved physical side is data-side on the popup.

type TooltipSide = "top" | "bottom" | "start" | "end"

TooltipTriggerProps type

import type { TooltipTriggerProps } from '@nizivo/react/tooltip'

The props of Tooltip.Trigger, listed above.

TooltipTriggerState type

import type { TooltipTriggerState } from '@nizivo/react/tooltip'

The render state of Tooltip.Trigger, listed above.

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-hit-target, .nz-tooltip-popup, .nz-tooltip-shortcut, .nz-tooltip-trigger. Runtime variables: --nz-transform-origin.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• tooltip-trigger: draws the focus outline itself on keyboard focus.

In forced-colours mode these states keep a visible system colour: tooltip-popup (border).

Behaviour comes from the react-aria engine through Nizivo's adapter: focus management, ARIA wiring and keyboard handling are the engine's.

Pattern: WAI-ARIA Authoring Practices.

KeyboardCopy Anchor Link

Source: react-aria-components 1.22.1 TooltipTrigger (react-aria 3.53.1 useTooltipTrigger) through _engines/react-aria/tooltip.client.tsx. Showing on keyboard focus and hiding on Escape are checked by the Next fixture and by apps/docs/scripts/smoke.ts.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: none
• Ghost masters: Figma node 746:262