XDS — Design System

XDSTooltip@xds/core · Tooltip

Usage

A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.

Best practices

Guidance	Practices
Do	Keep tooltip content concise — aim for under 140 characters of plain text.
Do	Add a tooltip to icon-only buttons and controls that lack a visible label.
Don't	Place interactive elements like links or buttons inside a tooltip — use HoverCard or Popover instead.
Don't	Use tooltips for essential information that users must see to complete a task.

Import

ts
import {XDSTooltip} from '@xds/core/Tooltip'

Props

Prop	Type	Description
children	ReactNode	Trigger element(s) that activate the tooltip.
anchorRef	RefObject<HTMLElement>	External anchor ref for sibling mode.
content	ReactNode	Tooltip content, typically short text.
placement	LayerPlacement (default: 'above')	Position relative to the anchor element.
alignment	LayerAlignment (default: 'center')	Alignment along the placement axis.
delay	number (default: 200)	Show delay in milliseconds.
hideDelay	number (default: 0)	Hide delay in milliseconds.
focusTrigger	'auto' \| 'always' \| 'never' (default: 'auto')	Controls when focus events trigger the tooltip.
isEnabled	boolean (default: true)	Enables or disables the tooltip triggers.
onOpenChange	(isOpen: boolean) => void	Callback fired when tooltip visibility changes. Called with true when shown and false when hidden.
hasHoverIndication	'auto' \| boolean (default: 'auto')	Shows a dashed underline on the trigger element.
isDefaultOpen	boolean	Whether the tooltip should be shown on mount. Still dismissible.

Sub-components

Tooltip is a compound component with 1 sub-component.

XDSTooltip

Component wrapper for tooltip display triggered on hover or focus.

Prop	Type	Description
children	ReactNode	Trigger element(s) that activate the tooltip.
anchorRef	RefObject<HTMLElement>	External anchor ref for sibling mode.
content	ReactNode	Tooltip content, typically short text.
placement	LayerPlacement (default: 'above')	Position relative to the anchor element.
alignment	LayerAlignment (default: 'center')	Alignment along the placement axis.
delay	number (default: 200)	Show delay in milliseconds.
hideDelay	number (default: 0)	Hide delay in milliseconds.
focusTrigger	'auto' \| 'always' \| 'never' (default: 'auto')	Controls when focus events trigger the tooltip.
isEnabled	boolean (default: true)	Enables or disables the tooltip triggers.
onOpenChange	(isOpen: boolean) => void	Callback fired when tooltip visibility changes. Called with true when shown and false when hidden.
hasHoverIndication	'auto' \| boolean (default: 'auto')	Shows a dashed underline on the trigger element.
isDefaultOpen	boolean	Whether the tooltip should be shown on mount. Still dismissible.

Examples

Common configurations, variations, and states.

Tooltip — Action BarTooltips on an action button bar with contextual descriptions.

tsx
'use client';
import {XDSTooltip} from '@xds/core/Tooltip';
import {XDSButton} from '@xds/core/Button';
import {XDSHStack} from '@xds/core/Layout';
import {XDSCenter} from '@xds/core/Center';
export default function TooltipActionBarTooltips() {
  return (
    <XDSCenter>
      <XDSHStack gap={4}>
        <XDSTooltip content="Save your changes" placement="above">
          <XDSButton label="Save" />
        </XDSTooltip>
        <XDSTooltip content="Discard changes" placement="above">
          <XDSButton label="Cancel" />
        </XDSTooltip>
        <XDSTooltip content="Delete permanently" placement="above">
          <XDSButton label="Delete" variant="destructive" />
        </XDSTooltip>
      </XDSHStack>
    </XDSCenter>
  );
}

Tooltip — Hook UsageTooltip using the useXDSTooltip hook for programmatic control.

tsx
'use client';
import {useXDSTooltip} from '@xds/core/Tooltip';
import {XDSButton} from '@xds/core/Button';
import {XDSCenter} from '@xds/core/Center';
export default function TooltipHookUsage() {
  const tooltip = useXDSTooltip({
    placement: 'above',
    delay: 100,
  });
  return (
    <XDSCenter>
      <XDSButton
        label="Using hook directly"
        ref={tooltip.ref}
        aria-describedby={tooltip.describedBy}
      />
      {tooltip.renderTooltip('Tooltip via hook')}
    </XDSCenter>
  );
}

Tooltip — Inline TextTooltips on inline text terms for definitions.

tsx
'use client';
import {XDSTooltip} from '@xds/core/Tooltip';
import {XDSText} from '@xds/core/Text';
export default function TooltipInlineTextTooltips() {
  return (
    <XDSText type="body">
      Learn more about our{' '}
      <XDSTooltip
        content="Your data is encrypted and never shared"
        placement="above">
        privacy policy
      </XDSTooltip>{' '}
      and{' '}
      <XDSTooltip content="Standard 30-day agreement" placement="above">
        terms of service
      </XDSTooltip>
      .
    </XDSText>
  );
}

Showcase source

tsx
'use client';
import {XDSTooltip} from '@xds/core/Tooltip';
import {XDSButton} from '@xds/core/Button';
export default function TooltipShowcase() {
  return (
    <XDSTooltip content="This is a helpful tooltip" placement="above" isDefaultOpen>
      <XDSButton label="Hover me" />
    </XDSTooltip>
  );
}