Tooltip

Beta

A short hint shown when an element is hovered or focused.

---
import Tooltip from "@/components/ui/tooltip/Tooltip.astro";
import Button from "@/components/ui/button/Button.astro";
---

<Tooltip text="Copy the link to this page">
  <Button variant="secondary">Copy link</Button>
</Tooltip>

Installation

npx eris-ui@latest add tooltip

pnpm dlx eris-ui@latest add tooltip

bunx eris-ui@latest add tooltip

yarn dlx eris-ui@latest add tooltip

Installs @zag-js/tooltip, @zag-js/vanilla.

Usage

Wrap the element the hint describes and pass the hint as text. The tooltip adds no element around it, so your layout stays the same.

The hint attaches to the first focusable element inside: a button, a link, an input, or anything with tabindex. To pick a different element, mark it data-tooltip-trigger. Put the hint on something focusable, or keyboard users never see it.

While the hint is showing, it is the trigger’s description for screen readers. It does not replace the trigger’s name, so an icon-only button still needs an aria-label.

Placement

placement picks the side of the trigger: top, bottom, left or right, each with an optional -start or -end. The default is top. gutter is the gap in pixels, 6 by default. The hint flips to the opposite side when it does not fit.

---
import Tooltip from "@/components/ui/tooltip/Tooltip.astro";
import Button from "@/components/ui/button/Button.astro";
---

<div class="flex flex-wrap justify-center gap-3">
  <Tooltip text="Above" placement="top">
    <Button variant="secondary">Top</Button>
  </Tooltip>
  <Tooltip text="Beside" placement="right">
    <Button variant="secondary">Right</Button>
  </Tooltip>
  <Tooltip text="Below, 12px away" placement="bottom" gutter={12}>
    <Button variant="secondary">Bottom</Button>
  </Tooltip>
</div>

Delay

The hint opens after the pointer rests for openDelay milliseconds, 400 by default, and closes closeDelay milliseconds after it leaves, 150 by default. Keyboard focus opens it at once.

---
import Tooltip from "@/components/ui/tooltip/Tooltip.astro";
import Button from "@/components/ui/button/Button.astro";
---

<div class="flex flex-wrap justify-center gap-3">
  <Tooltip text="Opens at once" openDelay={0} closeDelay={0}>
    <Button variant="secondary">No delay</Button>
  </Tooltip>
  <Tooltip text="Opens after a second" openDelay={1000}>
    <Button variant="secondary">Slow</Button>
  </Tooltip>
</div>

Markup in the hint

For more than plain text, leave text out and fill the content slot. Keep it short and do not put links or buttons in it: a tooltip cannot be reached with Tab. Use a Popover for that.

---
import Tooltip from "@/components/ui/tooltip/Tooltip.astro";
import Button from "@/components/ui/button/Button.astro";
import Kbd from "@/components/ui/kbd/Kbd.astro";
---

<Tooltip>
  <Button variant="secondary">Search</Button>
  <span slot="content" class="flex items-center gap-2">
    Search the docs <Kbd size="sm">/</Kbd>
  </span>
</Tooltip>

Set interactive to keep the hint open while the pointer is over it, so its text can be selected.

On another component’s trigger

A tooltip can wrap the trigger of a Dialog or Popover. Both keep working on the same button.

---
import Tooltip from "@/components/ui/tooltip/Tooltip.astro";
import Popover from "@/components/ui/popover/Popover.astro";
import PopoverTrigger from "@/components/ui/popover/PopoverTrigger.astro";
import PopoverContent from "@/components/ui/popover/PopoverContent.astro";
import PopoverTitle from "@/components/ui/popover/PopoverTitle.astro";
import PopoverDescription from "@/components/ui/popover/PopoverDescription.astro";
---

<Popover>
  <Tooltip text="Filter the list">
    <PopoverTrigger>Filters</PopoverTrigger>
  </Tooltip>
  <PopoverContent>
    <PopoverTitle>Filter by status</PopoverTitle>
    <PopoverDescription>Nothing to filter yet.</PopoverDescription>
  </PopoverContent>
</Popover>

Keyboard

Key	Does
`Tab`	Focusing the trigger shows the hint
`Esc`	Hides the hint. Focus stays where it is

Pressing the trigger also hides the hint, and only one hint shows at a time. Inside a Popover or Dialog, Esc hides the hint and closes the Popover or Dialog in one press.

Props

Prop	Default	Does
`text`	none	The hint. Use the `content` slot for markup
`placement`	`"top"`	Side of the trigger the hint opens on
`gutter`	`6`	Gap between trigger and hint, in pixels
`openDelay`	`400`	Milliseconds of hover before it opens
`closeDelay`	`150`	Milliseconds it stays after the pointer leaves
`interactive`	`false`	Stays open while the pointer is over the hint
`disabled`	`false`	Never shows the hint
`class`	none	Classes for the hint
`id`	random	Id for the instance, used to build the part ids