Skip to main content

Tooltip

Tooltip is an overlay for brief supporting text, like explaining an icon button or a truncated label. It appears while the trigger is hovered or has keyboard focus.

Import

import { Tooltip } from '@vortexlabs/vortex';
import type { TooltipProps } from '@vortexlabs/vortex';

Other links

Storybook

Features

  • Shows text on hover and keyboard focus.
  • Connects the tooltip to its trigger with aria-describedby.
  • Supports different positions, spacing, and maximum widths.
  • Renders only the trigger when tooltip text is absent.
Reference Links
WAI-ARIA tooltip pattern

Trigger Attributes

The children function receives trigger attributes. Forward them to the trigger element, like Button's attributes prop.

"use client";

import { Button, Tooltip } from "@vortexlabs/vortex";

export const TooltipExample = () => {
  return (
    <Tooltip text="Copy the link to this project">
      {(attributes) => <Button size="sm" attributes={attributes}>Copy link</Button>}
    </Tooltip>
  );
};

Icon Buttons

An icon button still needs ariaLabel; the tooltip adds context but doesn't replace it.

import { Hexagon } from "@vortexlabs/vortex-icons";

<Tooltip text="Open settings for the current workspace">
  {(attributes) => (
    <Button
      size="sm"
      onlyIcon={Hexagon}
      ariaLabel="Workspace settings"
      variant="secondary"
      attributes={attributes}
    />
  )}
</Tooltip>

Position

Each position pairs a side with an alignment, like top-start or end-center. The default is bottom-center; start and end follow the document direction.

<Tooltip text="Project details" position="top-center">
  {(attributes) => (
    <Button size="sm" variant="secondary" attributes={attributes}>
      top-center
    </Button>
  )}
</Tooltip>
<Tooltip text="Project details" position="bottom-center">
  {(attributes) => (
    <Button size="sm" variant="secondary" attributes={attributes}>
      bottom-center
    </Button>
  )}
</Tooltip>
<Tooltip text="Project details" position="start-center">
  {(attributes) => (
    <Button size="sm" variant="secondary" attributes={attributes}>
      start-center
    </Button>
  )}
</Tooltip>
<Tooltip text="Project details" position="end-center">
  {(attributes) => (
    <Button size="sm" variant="secondary" attributes={attributes}>
      end-center
    </Button>
  )}
</Tooltip>

Width and Spacing

Long text wraps at maxWidth, which defaults to 22.5rem. contentGap sets the space between the tooltip and its trigger, and defaults to 2.

<Tooltip
  text="Only workspace members can view this project. Invitations are managed in workspace settings."
  maxWidth="14rem"
  contentGap={4}
>
  {(attributes) => (
    <Button size="sm" variant="secondary" attributes={attributes}>
      Private project
    </Button>
  )}
</Tooltip>

Optional Content

When text is undefined, null, false, or empty, Tooltip renders only its trigger. Use it to show help only when it's relevant.

"use client";

import { Button, Checkbox, Stack, Tooltip } from "@vortexlabs/vortex";
import { useState } from "react";

export const TooltipOptionalExample = () => {
  const [showHelp, setShowHelp] = useState(true);

  return (
    <Stack gap={4} align="start">
      <Checkbox
        label="Show contextual help"
        checked={showHelp}
        onChange={({ checked }) => setShowHelp(checked)}
      />
      <Tooltip
        text={showHelp ? "Archive completed tasks without deleting them" : undefined}
      >
        {(attributes) => (
          <Button size="sm" variant="secondary" attributes={attributes}>
            Archive tasks
          </Button>
        )}
      </Tooltip>
    </Stack>
  );
};

Disabled

Set disabled to stop the tooltip from opening. The trigger stays interactive.

"use client";

import { Button, Checkbox, Stack, Tooltip } from "@vortexlabs/vortex";
import { useState } from "react";

export const TooltipDisabledExample = () => {
  const [disabled, setDisabled] = useState(false);

  return (
    <Stack gap={4} align="start">
      <Checkbox
        label="Disable the tooltip"
        checked={disabled}
        onChange={({ checked }) => setDisabled(checked)}
      />
      <Tooltip disabled={disabled} text="Create a copy in your workspace">
        {(attributes) => (
          <Button size="sm" variant="secondary" attributes={attributes}>
            Duplicate project
          </Button>
        )}
      </Tooltip>
    </Stack>
  );
};

Accessibility

Key
Description
Tab
Moving focus to the trigger shows the tooltip.
Escape
Hides the tooltip.
Give the trigger an accessible name that works without the tooltip.
Keep text to plain supporting text, without links or buttons.