---
title: Tooltip
description: Show supplemental, non-interactive information on hover or focus.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Tooltip

> Show supplemental, non-interactive information on hover or focus.

## Anatomy

```text
Tooltip [component; no DOM]
├── Tooltip.Trigger [part; slot=trigger]
└── positioner [internal]
    └── Tooltip.Content [part; slot=content]
        └── kbds [slot]
            └── item [internal]
```

Content is portaled into an internal positioning wrapper.

## Usage

Use Tooltip for supplemental information on hover or focus. Use [Popover](https://moraine.subf.dev/components/popover.md) when
the content is interactive. Use [Dialog](https://moraine.subf.dev/components/dialog.md) or [Sheet](https://moraine.subf.dev/components/sheet.md) for a
task that should take over the page. Do not rely on tooltip text as the only accessible name of a
control: the trigger needs its own name, such as visible text or `aria-label`. The trigger
references the content through `aria-describedby`.

```tsx
import { Button, Tooltip } from 'moraine'

export function Example() {
  return (
    <Tooltip>
      <Tooltip.Trigger as={Button}>Save</Tooltip.Trigger>
      <Tooltip.Content>Save changes</Tooltip.Content>
    </Tooltip>
  )
}
```

### Text and content

Pass plain text or JSX as children of `Tooltip.Content`. String children render in the `text` slot;
other children render directly inside the content. Set `variant="invert"` on `Tooltip` to flip the
colors.

```tsx
<Tooltip>
  <Tooltip.Trigger as={Button}>Deploy History</Tooltip.Trigger>
  <Tooltip.Content>View project deployment history and logs</Tooltip.Content>
</Tooltip>
```

### Triggering and shortcuts

Tooltip opens from pointer hover and keyboard focus. `kbds` displays shortcut notation after the
hint; it does not register that shortcut. Names such as `command`, `ctrl`, `shift`, and `meta`
render as symbols. Set `kbdVariant` on `Tooltip.Content` to `default`, `outline`, or `invert`. When
omitted, keycaps use `invert` if the tooltip's `variant` is `invert`, and `default` otherwise.

```tsx
<Tooltip>
  <Tooltip.Trigger as={Button} leading="i-lucide:save">
    Save
  </Tooltip.Trigger>
  <Tooltip.Content kbds={['command', 's']} kbdVariant="outline">
    Save changes
  </Tooltip.Content>
</Tooltip>
```

### Delays and grouped tooltips

`openDelay` (default 600 ms) waits before opening from hover or focus, and `closeDelay` (default
200 ms) lets the pointer move from the trigger onto the content without closing it. Set either to
`0` for no delay. After one tooltip closes, any tooltip in the same document opens without
`openDelay` for `skipDelay` (default 300 ms), so moving across a toolbar does not wait on every
button; set it to `0` to disable the grace period. `placement` defaults to `'top'`, and `gutter`
defaults to 4 px.

Control the open state with `open` and `onOpenChange`, or start open with `defaultOpen`. `disabled`
keeps the tooltip closed, and `forceMount` keeps its content in the DOM while closed.

### Keyboard interaction

Moving keyboard focus to the trigger opens the tooltip, and blurring it closes the tooltip. Pressing
the trigger dismisses the tooltip so a click does not leave it open.

## Examples

### Explain a labeled command

Hover or focus Deploy History for a longer description. The button already has a visible name.

```tsx
import { Button, Tooltip } from 'moraine'

export function HintsUsage() {
  return (
    <div class="flex gap-4 items-center">
      <Tooltip>
        <Tooltip.Trigger as={Button} variant="outline">
          Deploy History
        </Tooltip.Trigger>
        <Tooltip.Content>View project deployment history and logs</Tooltip.Content>
      </Tooltip>
    </div>
  )
}
```

### Show a save shortcut

`kbds` is display-only. Pair it with a labeled Save control.

```tsx
import { Button, Tooltip } from 'moraine'

export function ShortcutsUsage() {
  return (
    <div class="flex gap-4 items-center">
      <Tooltip>
        <Tooltip.Trigger as={Button} leading="i-lucide:save">
          Save
        </Tooltip.Trigger>
        <Tooltip.Content kbds={['command', 's']} kbdVariant="outline">
          Save changes
        </Tooltip.Content>
      </Tooltip>
    </div>
  )
}
```

### Label editor toolbar shortcuts

Keep icon-only controls named with `aria-label`. Each tooltip repeats the command and shows its
shortcut.

```tsx
import { Button, Tooltip } from 'moraine'

export function KeyboardShortcuts() {
  return (
    <div class="p-2 b-1 b-border rounded-xl bg-card flex flex-wrap gap-2 items-center">
      <Tooltip>
        <Tooltip.Trigger as={Button} variant="outline" size="sm" leading="i-lucide:save">
          Save
        </Tooltip.Trigger>
        <Tooltip.Content kbds={['⌘', 'S']}>Save changes</Tooltip.Content>
      </Tooltip>

      <Tooltip>
        <Tooltip.Trigger
          as={Button}
          variant="ghost"
          size="sm"
          leading="i-lucide:bold"
          aria-label="Bold"
        />
        <Tooltip.Content kbds={['⌘', 'B']}>Bold formatting</Tooltip.Content>
      </Tooltip>

      <Tooltip>
        <Tooltip.Trigger
          as={Button}
          variant="ghost"
          size="sm"
          leading="i-lucide:italic"
          aria-label="Italic"
        />
        <Tooltip.Content kbds={['⌘', 'I']}>Italic formatting</Tooltip.Content>
      </Tooltip>

      <Tooltip>
        <Tooltip.Trigger
          as={Button}
          variant="ghost"
          size="sm"
          leading="i-lucide:code"
          aria-label="Code"
        />
        <Tooltip.Content kbds={['⌘', 'E']}>Insert Code Block</Tooltip.Content>
      </Tooltip>

      <Tooltip>
        <Tooltip.Trigger
          as={Button}
          variant="ghost"
          size="sm"
          leading="i-lucide:search"
          aria-label="Search"
        />
        <Tooltip.Content kbds={['⌘', 'K']}>Quick Search</Tooltip.Content>
      </Tooltip>
    </div>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-closed` | `tooltip-trigger`, `tooltip-content` | Present when disclosure or transition content is closed. |
| `data-disabled` | `tooltip-trigger` | Present when the component, slot, or item is disabled. |
| `data-expanded` | `tooltip-trigger`, `tooltip-content` | Present when the panel, accordion, or menu is expanded. |
| `data-align` | `tooltip-content` | Stores the resolved alignment of positioned content. |
| `data-instant-motion` | `tooltip-content` | Present when enter and exit motion should complete immediately. |
| `data-side` | `tooltip-content` | Stores the resolved floating or drawer content side. |

### Props

#### Tooltip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| align | 'start' \| 'center' \| 'end' \| undefined | 'center' | Alignment of the content along the trigger edge: `'start'` and `'end'` line up the content<br>edge with the matching trigger edge, `'center'` centers it. Combines with `placement`. |
| closeDelay | number \| undefined | 200 | Delay in milliseconds between the pointer leaving the trigger and content and closing;<br>moving onto the content keeps the tooltip open. `0` closes immediately. |
| defaultOpen | boolean \| undefined | false | Initial open state when uncontrolled. Ignored while `open` is set. |
| disabled | boolean \| undefined | false | Whether trigger interactions and content rendering are disabled. |
| flip | boolean \| string \| undefined | true | Whether the content moves to another side when the preferred `placement` does not fit in the<br>viewport. `false` keeps the side fixed. A string is a space-delimited list of fallback<br>placements tried in order, each `top`, `right`, `bottom` or `left`, optionally suffixed with<br>`-start` or `-end`; any other entry throws an error. |
| forceMount | boolean \| undefined | false | Whether the content stays in the DOM while closed, hidden and marked with `data-closed`, for<br>example to measure it or keep its state. Has no effect while `disabled`. |
| gutter | number \| undefined | 4 | Gap in pixels between the trigger and the content. |
| id | string \| undefined | — | Unique identifier used to derive the content id, which becomes `<id>-content`. Generated when<br>omitted. |
| onOpenChange | ((open: boolean) => void) \| undefined | — | Called with the next open state when an interaction (trigger press, hover or focus delay,<br>Escape, outside press) requests a change. It is not called when `open` is changed from outside,<br>and it does not apply the change itself when `open` is controlled: update `open` in the handler. |
| open | boolean \| undefined | — | Controlled open state. Pair it with `onOpenChange`; leave it `undefined` to let the component<br>manage its own state (see `defaultOpen`). `disabled` forces the content closed regardless. |
| openDelay | number \| undefined | 600 | Delay in milliseconds between pointer hover or keyboard focus on the trigger and opening;<br>`0` opens immediately. The delay is skipped while another tooltip is open or within<br>`skipDelay` of one closing. |
| overflowPadding | number \| undefined | 4 | Minimum padding in pixels between the content and the viewport edge. |
| placement | 'top' \| 'right' \| 'bottom' \| 'left' \| undefined | 'top' | Preferred side of the trigger the tooltip appears on (`'top'`, `'right'`, `'bottom'` or<br>`'left'`). It may move to another side when `flip` is enabled and the side lacks space. |
| shift | number \| undefined | 0 | Offset in pixels along the trigger edge (horizontal for `top` and `bottom` placements,<br>vertical for `left` and `right`), added to the position given by `align`. |
| skipDelay | number \| undefined | 300 | Duration in milliseconds after a tooltip closes during which any tooltip in the same document<br>opens without `openDelay`, so moving across a toolbar does not wait on every button. `0`<br>disables the grace period. |
| slide | boolean \| undefined | true | Whether the content slides along the trigger edge (horizontally for `top` and `bottom`<br>placements, vertically for `left` and `right`) to stay inside the viewport, keeping<br>`overflowPadding` from the edge, instead of overflowing. |
| variant | 'default' \| 'invert' \| undefined | 'default' | `invert` flips the colors (e.g. dark tooltip on light theme). |
| children | JSX.Element \| undefined | — | Composed trigger and content primitives. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`flip` example**

```tsx
import { Button, Popover } from 'moraine'

<Popover placement="bottom" flip="top bottom-end">
  <Popover.Trigger as={Button}>Details</Popover.Trigger>
  <Popover.Content>More information</Popover.Content>
</Popover>
```

**`onOpenChange` example**

```tsx
import { Button, Popover } from 'moraine'
import { createSignal } from 'solid-js'

const [open, setOpen] = createSignal(false)

<Popover open={open()} onOpenChange={setOpen}>
  <Popover.Trigger as={Button}>Details</Popover.Trigger>
  <Popover.Content>More information</Popover.Content>
</Popover>
```

#### Tooltip.Trigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| disabled | boolean \| undefined | — | Whether this trigger is disabled. |
| as | T \| undefined | 'button' | Element or component to render as. |
| children | JSX.Element \| undefined | — | Trigger label and visual content. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |

#### Tooltip.Content

Props for the Tooltip component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| kbds | string[] \| undefined | — | Keys shown as keycaps after the text, for example `['command', 's']`. Names such as `meta`,<br>`ctrl`, `shift` and `command` render as symbols. This only displays the shortcut; it does not<br>register it. |
| kbdVariant | 'default' \| 'outline' \| 'invert' \| undefined | — | Visual variant of the shortcut keycaps (`'default'`, `'outline'` or `'invert'`). When omitted,<br>keycaps use `'invert'` if the tooltip itself has `variant="invert"` and the default otherwise. |
| children | JSX.Element \| undefined | — | Tooltip text or element. A string is wrapped in the `text` slot; other nodes render as given. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |

**`kbds` example**

```tsx
import { Button, Tooltip } from 'moraine'

<Tooltip>
  <Tooltip.Trigger as={Button}>Search</Tooltip.Trigger>
  <Tooltip.Content kbds={['meta', 'k']}>Search the docs</Tooltip.Content>
</Tooltip>
```
