Tooltip

A popup overlay that displays additional information when hovering over or focusing on a trigger element. Supports color variants, an optional arrow, and configurable positioning, delay duration, and max width.

A Tooltip renders its children as its trigger, so they should be an interactive element, like a Button or an IconButton. To attach a Tooltip to non-interactive content, like an icon or plain text, use the wrapWithButton prop to wrap it in a <button> trigger instead.

import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function TooltipDemo() {
  return (
    <Tooltip content="This is a tooltip">
      <Button variant="subtle">Hover me</Button>
    </Tooltip>
  );
}

Options

PropTypeDescriptionDefault
contentReactNodeThe content displayed inside the tooltip popup.—
variant"contrast" | "danger"The visual variant of the tooltip, which determines its color scheme."contrast"
hideArrowbooleanWhen true, hides the arrow pointing from the tooltip to its trigger.false
side"top" | "right" | "bottom" | "left"The preferred side to render the tooltip against."top"
sideOffsetnumberThe distance in pixels from the trigger to the tooltip, not counting the arrow height. When hideArrow is true, this is the full distance.4
align"center" | "start" | "end"The alignment of the tooltip relative to the trigger."center"
alignOffsetnumberAn offset in pixels from the aligned edge.0
openbooleanControls the open state of the tooltip (controlled mode).—
onOpenChange(value: boolean) => voidCallback fired when the open state changes.—
delayDurationnumberDuration in milliseconds to wait before showing the tooltip.500
defaultOpenbooleanWhether the tooltip is open by default (uncontrolled mode).false
maxWidthnumberThe maximum width of the tooltip in pixels. Content wraps if exceeded.240
containerHTMLElement | ShadowRoot | null | RefObject<HTMLElement | ShadowRoot | null>Specify the element or shadow root to portal the tooltip into.–
childrenReactNodeThe trigger that the tooltip is attached to, or the content of the trigger when wrapWithButton is true.—
wrapWithButtonbooleanWraps children in a <button> trigger instead of rendering children as the trigger itself. Use for non-interactive content.false

All other props are forwarded to children by default, or the wrapping <button> element that gets rendered when wrapWithButton is true.

Examples

Basic usage

Render a Tooltip by wrapping children with it and giving it content. content can be any ReactNode, though it is highly advisable to just render plain text:

import { IconButton } from "@tenstorrent/vesper/icon-button";
import { Download } from "@tenstorrent/vesper/icons";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function BasicTooltip() {
  return (
    <Tooltip content="Download documents">
      <IconButton
        aria-label="Download"
        variant="contrast"
        icon={<Download />}
      />
    </Tooltip>
  );
}
A Tooltip forwards its trigger's props to its children. Its children must be a single React element that passes every prop it receives on to the DOM element it renders.

Wrapping non-interactive content

Non-interactive content, like icons and text, can't be focused, so a Tooltip rendering it as its trigger can't be opened with a keyboard. Pass wrapWithButton to wrap children in a <button> trigger instead. When children has no text of its own, give the tooltip an accessible name via aria-label:

Throughput

import { Info } from "@tenstorrent/vesper/icons";
import { Tooltip } from "@tenstorrent/vesper/tooltip";
import { Typography } from "@tenstorrent/vesper/typography";

export default function WrappedTooltip() {
  return (
    <div
      style={{
        display: "flex",
        alignItems: "center",
        gap: "var(--vesper-spacing-2)",
      }}
    >
      <Typography>Throughput</Typography>
      <Tooltip
        wrapWithButton
        side="right"
        content="Tokens generated per second"
        aria-label="About throughput"
      >
        <Info style={{ display: "block", width: 16 }} />
      </Tooltip>
    </div>
  );
}

wrapWithButton renders an unstyled <button>. Any props that a Tooltip doesn't own, like className and style, are forwarded to it, so you can style it as needed.

A Tooltip always wraps children that aren't a single React element (eg. plain text, a fragment, or multiple elements) in a <button> trigger, even when wrapWithButton is false.

Variants

A Tooltip can be rendered in one of two variants:

VariantWhen to use
"contrast"Default variant. Use for general-purpose informational content.
"danger"Use to warn about destructive actions, or to explain an error state on its trigger.
import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function TooltipVariants() {
  return (
    <div
      style={{
        display: "flex",
        justifyContent: "center",
        gap: "var(--vesper-spacing-16)",
        paddingTop: "var(--vesper-spacing-12)",
      }}
    >
      <Tooltip open variant="contrast" content="Contrast variant tooltip">
        <Button variant="subtle">Trigger</Button>
      </Tooltip>
      <Tooltip open variant="danger" content="Danger variant tooltip">
        <Button variant="subtle">Trigger</Button>
      </Tooltip>
    </div>
  );
}
Don't rely on color alone to convey meaning. When using the "danger" variant, make sure the tooltip's content also describes the risk or error in words.

Hiding the arrow

By default, a Tooltip renders an arrow pointing to its trigger. Pass hideArrow to render the tooltip without one:

import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function TooltipWithoutArrow() {
  return (
    <div
      style={{
        display: "flex",
        justifyContent: "center",
        gap: "var(--vesper-spacing-24)",
        paddingTop: "var(--vesper-spacing-12)",
      }}
    >
      <Tooltip open content="With arrow">
        <Button variant="subtle">Trigger</Button>
      </Tooltip>
      <Tooltip open hideArrow content="Without arrow">
        <Button variant="subtle">Trigger</Button>
      </Tooltip>
    </div>
  );
}

The arrow's height normally adds to the gap between a Tooltip and its trigger. When hideArrow is true, that space is removed, so the gap is determined by sideOffset alone.

Positioning the tooltip

By default, a Tooltip floats above and is aligned to the center of its trigger. You can adjust the positioning of a Tooltip via the side, sideOffset, align, and alignOffset props.

The side prop determines which trigger edge the Tooltip sits against. Possible values are "top", "right", "bottom", and "left". The default value is "top".

The sideOffset prop determines how far away in pixels the Tooltip is from its trigger's edge, not counting the height of its arrow. When hideArrow is true, sideOffset is the full distance. The default value is 4. This value scales with the base rem size.

The align prop determines which end of the side to align the Tooltip to. Possible values are "start", "end", and "center". The default value is "center".

The alignOffset prop adjusts how many pixels the Tooltip is offset from its alignment. The default value is 0. This value scales with the base rem size.

The demo below shows how the side and align props interact with each other:

import { useState } from "react";

import { Button } from "@tenstorrent/vesper/button";
import { Select } from "@tenstorrent/vesper/select";
import {
  Tooltip,
  TOOLTIP_ALIGNMENTS,
  TOOLTIP_SIDES,
  type TooltipAlign,
  type TooltipSide,
} from "@tenstorrent/vesper/tooltip";

export default function TooltipPositionPlayground() {
  const [side, setSide] = useState<TooltipSide>("top");
  const [align, setAlign] = useState<TooltipAlign>("center");

  return (
    <div
      style={{ display: "flex", flexDirection: "column", alignItems: "center" }}
    >
      <Tooltip
        open
        side={side}
        align={align}
        content={`${side} side, ${align} align`}
      >
        <Button
          style={{
            marginTop: "var(--vesper-spacing-16)",
            marginBottom: "var(--vesper-spacing-20)",
          }}
        >
          Trigger
        </Button>
      </Tooltip>
      <div style={{ display: "flex", gap: "var(--vesper-spacing-4)" }}>
        <Select
          value={side}
          aria-label="Tooltip side"
          onValueChange={(side) => setSide(side as TooltipSide)}
          options={[...TOOLTIP_SIDES]}
          style={{ width: "var(--vesper-spacing-28)" }}
        />
        <Select
          value={align}
          aria-label="Tooltip align"
          onValueChange={(align) => setAlign(align as TooltipAlign)}
          options={[...TOOLTIP_ALIGNMENTS]}
          style={{ width: "var(--vesper-spacing-28)" }}
        />
      </div>
    </div>
  );
}

Adjusting the delay

A Tooltip does not instantly show when a user hovers its trigger. By default, a half-second delay occurs prior to showing a Tooltip. This duration can be adjusted via the delayDuration prop, which represents the amount of milliseconds to wait before showing a Tooltip:

import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function TooltipDelays() {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        alignItems: "flex-start",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <Tooltip
        content="This tooltip appears instantly"
        delayDuration={0}
        side="right"
      >
        <Button variant="contrast">No delay</Button>
      </Tooltip>
      <Tooltip
        content="This tooltip appears delayed"
        delayDuration={1000}
        side="right"
      >
        <Button variant="contrast">1 second delay</Button>
      </Tooltip>
    </div>
  );
}

Setting the max width

The default maximum width a Tooltip can render at before its content wraps is 240 pixels. You can adjust this by passing a numeric value to the maxWidth prop. This value scales with the base rem size:

import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function WideTooltip() {
  return (
    <Tooltip
      content="This tooltip contains a longer description that will wrap at the specified max width."
      maxWidth={320}
      side="right"
    >
      <Button variant="contrast">Details</Button>
    </Tooltip>
  );
}

Controlling the open state

By default, a Tooltip tracks its own open state. If you need to control the open state of a Tooltip, you can do so via the open prop:

import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function ControlledTooltips() {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        alignItems: "flex-start",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <Tooltip content="This tooltip is always showing" side="right" open>
        <Button variant="subtle">Hover me</Button>
      </Tooltip>
      <Tooltip content="This tooltip never shows" side="right" open={false}>
        <Button variant="subtle">Hover me</Button>
      </Tooltip>
    </div>
  );
}

Pair open with onOpenChange when you want to keep tracking hover and focus while still owning the state, eg. to keep a tooltip open while another part of the page is interacting with its trigger:

import { useState } from "react";

import { Button } from "@tenstorrent/vesper/button";
import { Checkbox } from "@tenstorrent/vesper/checkbox";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function ControlledTooltip() {
  const [open, setOpen] = useState(false);
  const [pinned, setPinned] = useState(false);

  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        alignItems: "flex-start",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <Tooltip
        content="The tooltip content"
        side="right"
        open={pinned || open}
        onOpenChange={setOpen}
      >
        <Button variant="subtle">Hover me</Button>
      </Tooltip>
      <Checkbox
        text="Keep the tooltip open"
        checked={pinned}
        onChange={(event) => setPinned(event.target.checked)}
      />
    </div>
  );
}

Listening for open's value changing

You can respond to open's value changing via the onOpenChange prop:

Open state: false

import { useState } from "react";

import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";
import { Typography } from "@tenstorrent/vesper/typography";

export default function TooltipOpenChange() {
  const [open, setOpen] = useState(false);

  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        alignItems: "flex-start",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <Tooltip
        content="The tooltip content"
        side="right"
        onOpenChange={(open) => setOpen(open)}
      >
        <Button variant="subtle">Hover me</Button>
      </Tooltip>
      <Typography variant="copy-sm">Open state: {String(open)}</Typography>
    </div>
  );
}

Showing by default

Pass defaultOpen to show a Tooltip before the first user interaction. Because this is uncontrolled mode, normal interactions can subsequently close it (pressing Escape or moving the pointer away after hovering, for example):

import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function DefaultOpenTooltip() {
  return (
    <Tooltip content="This tooltip shows by default" side="right" defaultOpen>
      <Button variant="subtle">Hover me</Button>
    </Tooltip>
  );
}