Tooltip

A small popup that appears when hovering over or focusing on an element. Positioning is computed in JavaScript.

1
---
2
import { Button } from '@bejamas/registry/ui/button';
3
import { Tooltip, TooltipContent, TooltipTrigger } from '@bejamas/registry/ui/tooltip';
4
---
5

6
<Tooltip>
7
  <TooltipTrigger asChild>
8
    <Button variant="outline">Hover</Button>
9
  </TooltipTrigger>
10
  <TooltipContent>
11
    <p>Add to library</p>
12
  </TooltipContent>
13
</Tooltip>

Installation

bunx bejamas add tooltip

npx bejamas add tooltip

pnpm dlx bejamas add tooltip

yarn dlx bejamas add tooltip

Usage

1
---
2
import { Tooltip, TooltipTrigger, TooltipContent } from '@bejamas/ui/components/tooltip';
3
import { Button } from '@bejamas/ui/components/button';
4
---
5

6
<Tooltip>
7
  <TooltipTrigger asChild>
8
    <Button variant="outline">Hover</Button>
9
  </TooltipTrigger>
10
  <TooltipContent>
11
    <p>Add to library</p>
12
  </TooltipContent>
13
</Tooltip>

Props

Prop	Type	Default
`class`	`string`	`""`
`delay`	`number`	`300`
`skipDelayDuration`	`number`	`300`

Examples

With delay

1
---
2
import { Button } from '@bejamas/registry/ui/button';
3
import { Tooltip, TooltipContent, TooltipTrigger } from '@bejamas/registry/ui/tooltip';
4
---
5

6
<Tooltip delay={1000}>
7
  <TooltipTrigger asChild>
8
    <Button variant="outline">Hover with delay</Button>
9
  </TooltipTrigger>
10
  <TooltipContent>
11
    <p>This tooltip appears after 1000ms</p>
12
  </TooltipContent>
13
</Tooltip>

Skip delay on subsequent tooltips

When a tooltip is shown, hovering over other tooltip triggers will show their tooltips immediately without delay. Try hovering over the first button, then quickly move to the others.

1
---
2
import { Button } from '@bejamas/registry/ui/button';
3
import { Tooltip, TooltipContent, TooltipTrigger } from '@bejamas/registry/ui/tooltip';
4
---
5

6
<div class="flex gap-2">
7
  <Tooltip delay={500}>
8
    <TooltipTrigger asChild>
9
      <Button variant="outline">Bold</Button>
10
    </TooltipTrigger>
11
    <TooltipContent>
12
      <p>Bold (Ctrl+B)</p>
13
    </TooltipContent>
14
  </Tooltip>
15
  <Tooltip delay={500}>
16
    <TooltipTrigger asChild>
17
      <Button variant="outline">Italic</Button>
18
    </TooltipTrigger>
19
    <TooltipContent>
20
      <p>Italic (Ctrl+I)</p>
21
    </TooltipContent>
22
  </Tooltip>
23
  <Tooltip delay={500}>
24
    <TooltipTrigger asChild>
25
      <Button variant="outline">Underline</Button>
26
    </TooltipTrigger>
27
    <TooltipContent>
28
      <p>Underline (Ctrl+U)</p>
29
    </TooltipContent>
30
  </Tooltip>
31
</div>

Different sides

Use the side prop to control which side the tooltip appears on.

1
---
2
import { Button } from '@bejamas/registry/ui/button';
3
import { Tooltip, TooltipContent, TooltipTrigger } from '@bejamas/registry/ui/tooltip';
4
---
5

6
<div class="grid gap-4 py-8">
7
  <div class="flex gap-4 items-center justify-center">
8
    <Tooltip>
9
      <TooltipTrigger asChild>
10
        <Button variant="outline">Left</Button>
11
      </TooltipTrigger>
12
      <TooltipContent side="left">
13
        <p>Tooltip on left</p>
14
      </TooltipContent>
15
    </Tooltip>
16
    <Tooltip>
17
      <TooltipTrigger asChild>
18
        <Button variant="outline">Top</Button>
19
      </TooltipTrigger>
20
      <TooltipContent side="top">
21
        <p>Tooltip on top</p>
22
      </TooltipContent>
23
    </Tooltip>
24
    <Tooltip>
25
      <TooltipTrigger asChild>
26
        <Button variant="outline">Bottom</Button>
27
      </TooltipTrigger>
28
      <TooltipContent side="bottom">
29
        <p>Tooltip on bottom</p>
30
      </TooltipContent>
31
    </Tooltip>
32
    <Tooltip>
33
      <TooltipTrigger asChild>
34
        <Button variant="outline">Right</Button>
35
      </TooltipTrigger>
36
      <TooltipContent side="right">
37
        <p>Tooltip on right</p>
38
      </TooltipContent>
39
    </Tooltip>
40
  </div>
41
  <div class="flex gap-4 items-center justify-center">
42
    <Tooltip>
43
      <TooltipTrigger asChild>
44
        <Button variant="outline">Inline Start</Button>
45
      </TooltipTrigger>
46
      <TooltipContent side="inline-start">
47
        <p>Tooltip on inline start</p>
48
      </TooltipContent>
49
    </Tooltip>
50
    <Tooltip>
51
      <TooltipTrigger asChild>
52
        <Button variant="outline">Inline End</Button>
53
      </TooltipTrigger>
54
      <TooltipContent side="inline-end">
55
        <p>Tooltip on inline end</p>
56
      </TooltipContent>
57
    </Tooltip>
58
  </div>
59
</div>

Alignment options

Use the align prop to control how the tooltip aligns relative to the trigger.

1
---
2
import { Button } from '@bejamas/registry/ui/button';
3
import { Tooltip, TooltipContent, TooltipTrigger } from '@bejamas/registry/ui/tooltip';
4
---
5

6
<div class="flex flex-col gap-4 items-center py-8">
7
  <div class="flex gap-4">
8
    <Tooltip>
9
      <TooltipTrigger asChild>
10
        <Button variant="outline">Top Start</Button>
11
      </TooltipTrigger>
12
      <TooltipContent side="top" align="start">
13
        <p>Aligned to start</p>
14
      </TooltipContent>
15
    </Tooltip>
16
    <Tooltip>
17
      <TooltipTrigger asChild>
18
        <Button variant="outline">Top Center</Button>
19
      </TooltipTrigger>
20
      <TooltipContent side="top" align="center">
21
        <p>Aligned to center</p>
22
      </TooltipContent>
23
    </Tooltip>
24
    <Tooltip>
25
      <TooltipTrigger asChild>
26
        <Button variant="outline">Top End</Button>
27
      </TooltipTrigger>
28
      <TooltipContent side="top" align="end">
29
        <p>Aligned to end</p>
30
      </TooltipContent>
31
    </Tooltip>
32
  </div>
33
  <div class="flex gap-4">
34
    <Tooltip>
35
      <TooltipTrigger asChild>
36
        <Button variant="outline">Bottom Start</Button>
37
      </TooltipTrigger>
38
      <TooltipContent side="bottom" align="start">
39
        <p>Aligned to start</p>
40
      </TooltipContent>
41
    </Tooltip>
42
    <Tooltip>
43
      <TooltipTrigger asChild>
44
        <Button variant="outline">Bottom Center</Button>
45
      </TooltipTrigger>
46
      <TooltipContent side="bottom" align="center">
47
        <p>Aligned to center</p>
48
      </TooltipContent>
49
    </Tooltip>
50
    <Tooltip>
51
      <TooltipTrigger asChild>
52
        <Button variant="outline">Bottom End</Button>
53
      </TooltipTrigger>
54
      <TooltipContent side="bottom" align="end">
55
        <p>Aligned to end</p>
56
      </TooltipContent>
57
    </Tooltip>
58
  </div>
59
</div>

Positioning Options

Use TooltipContent props to configure placement:

1
---
2
import { Button } from '@bejamas/registry/ui/button';
3
import { Tooltip, TooltipContent, TooltipTrigger } from '@bejamas/registry/ui/tooltip';
4
---
5

6
<div class="flex gap-3">
7
  <Tooltip>
8
    <TooltipTrigger asChild>
9
      <Button variant="outline">Offset</Button>
10
    </TooltipTrigger>
11
    <TooltipContent sideOffset={8}>
12
      <p>More distance from trigger</p>
13
    </TooltipContent>
14
  </Tooltip>
15
  <Tooltip>
16
    <TooltipTrigger asChild>
17
      <Button variant="outline">Align offset</Button>
18
    </TooltipTrigger>
19
    <TooltipContent side="bottom" align="start" alignOffset={12}>
20
      <p>Shifted on alignment axis</p>
21
    </TooltipContent>
22
  </Tooltip>
23
</div>

Disabled

1
---
2
import { Button } from '@bejamas/registry/ui/button';
3
import { Tooltip, TooltipContent, TooltipTrigger } from '@bejamas/registry/ui/tooltip';
4
---
5

6
<Tooltip>
7
  <TooltipTrigger asChild>
8
    <Button variant="outline" disabled>Disabled</Button>
9
  </TooltipTrigger>
10
  <TooltipContent>
11
    <p>This feature is currently unavailable</p>
12
  </TooltipContent>
13
</Tooltip>

API Reference

Events

The tooltip emits custom events that you can listen to:

Event	Detail	Description
`tooltip:change`	`{ open: boolean, trigger: HTMLElement, content: HTMLElement, reason: string }`	Fired when visibility changes

1
<Tooltip id="my-tooltip">
2
  <TooltipTrigger asChild>
3
    <Button variant="outline">Hover me</Button>
4
  </TooltipTrigger>
5
  <TooltipContent>
6
    <p>Tooltip content</p>
7
  </TooltipContent>
8
</Tooltip>

  const tooltip = document.getElementById('my-tooltip');

  tooltip.addEventListener('tooltip:change', (e) => {
    console.log('Is open:', e.detail.open);
    console.log('Reason:', e.detail.reason);
  });

Programmatic Control

You can control the tooltip programmatically by dispatching a tooltip:set event:

const tooltip = document.getElementById('my-tooltip');

// Show the tooltip
tooltip.dispatchEvent(new CustomEvent('tooltip:set', {
  detail: { open: true }
}));

// Hide the tooltip
tooltip.dispatchEvent(new CustomEvent('tooltip:set', {
  detail: { open: false }
}));

The deprecated { value: boolean } detail shape is still supported temporarily for compatibility, but new code should always use { open: boolean }.

Data Attributes

The tooltip sets these data attributes that you can use for styling or querying state:

Attribute	Element	Description
`data-state`	tooltip, tooltip-content	Legacy `"open"` / `"closed"` compatibility shim. Prefer `data-open` / `data-closed`.
`data-open` / `data-closed`	tooltip, tooltip-content, tooltip-positioner, tooltip-arrow	Present while open/closed
`data-starting-style` / `data-ending-style`	tooltip-content	Present while opening or closing
`data-instant`	tooltip, tooltip-content, tooltip-positioner, tooltip-arrow	Interaction reason: `"delay"`, `"focus"`, or `"dismiss"`
`data-side`	tooltip-content, tooltip-positioner, tooltip-arrow	Runtime side (`top`, `right`, `bottom`, `left`, `inline-start`, or `inline-end`) after collision handling
`data-align`	tooltip-content, tooltip-positioner, tooltip-arrow	Runtime alignment (`start`, `center`, or `end`)
`data-side-offset`	tooltip-content	Distance from trigger in pixels (default `4`)
`data-align-offset`	tooltip-content	Alignment-axis offset in pixels (default `0`)