---
title: Tooltip
description: Hover text that appears on any component.
icon: comment
---

import { ComponentPreview } from '/snippets/component-preview.mdx'

Tooltips show brief helper text when users hover over a component. Wrap any single element to add a tooltip. For richer hover content like status previews or structured data, use [HoverCard](/components/hover-card). For interactive content that stays open until dismissed, use [Popover](/components/popover).

## Basic Usage

<ComponentPreview height="140px" json={{"view":{"cssClass":"gap-4","type":"Row","children":[{"type":"Tooltip","content":"Save your current work","children":[{"type":"Button","label":"Save","variant":"default","size":"default","disabled":false}]},{"type":"Tooltip","content":"Discard unsaved changes","side":"bottom","children":[{"type":"Button","label":"Reset","variant":"outline","size":"default","disabled":false}]}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQnV0dG9uLCBSb3csIFRvb2x0aXAKCndpdGggUm93KGdhcD00KToKICAgIHdpdGggVG9vbHRpcCgiU2F2ZSB5b3VyIGN1cnJlbnQgd29yayIpOgogICAgICAgIEJ1dHRvbigiU2F2ZSIpCiAgICB3aXRoIFRvb2x0aXAoIkRpc2NhcmQgdW5zYXZlZCBjaGFuZ2VzIiwgc2lkZT0iYm90dG9tIik6CiAgICAgICAgQnV0dG9uKCJSZXNldCIsIHZhcmlhbnQ9Im91dGxpbmUiKQo=">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Button, Row, Tooltip

with Row(gap=4):
    with Tooltip("Save your current work"):
        Button("Save")
    with Tooltip("Discard unsaved changes", side="bottom"):
        Button("Reset", variant="outline")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Row",
    "children": [
      {
        "type": "Tooltip",
        "content": "Save your current work",
        "children": [
          {
            "type": "Button",
            "label": "Save",
            "variant": "default",
            "size": "default",
            "disabled": false
          }
        ]
      },
      {
        "type": "Tooltip",
        "content": "Discard unsaved changes",
        "side": "bottom",
        "children": [
          {
            "type": "Button",
            "label": "Reset",
            "variant": "outline",
            "size": "default",
            "disabled": false
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Side Placement

Control which side the tooltip appears on with the `side` parameter.

<ComponentPreview height="140px" json={{"view":{"cssClass":"gap-4","type":"Row","children":[{"type":"Tooltip","content":"Top","side":"top","children":[{"type":"Button","label":"Top","variant":"outline","size":"default","disabled":false}]},{"type":"Tooltip","content":"Right","side":"right","children":[{"type":"Button","label":"Right","variant":"outline","size":"default","disabled":false}]},{"type":"Tooltip","content":"Bottom","side":"bottom","children":[{"type":"Button","label":"Bottom","variant":"outline","size":"default","disabled":false}]},{"type":"Tooltip","content":"Left","side":"left","children":[{"type":"Button","label":"Left","variant":"outline","size":"default","disabled":false}]}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Button, Row, Tooltip

with Row(gap=4):
    with Tooltip("Top", side="top"):
        Button("Top", variant="outline")
    with Tooltip("Right", side="right"):
        Button("Right", variant="outline")
    with Tooltip("Bottom", side="bottom"):
        Button("Bottom", variant="outline")
    with Tooltip("Left", side="left"):
        Button("Left", variant="outline")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Row",
    "children": [
      {
        "type": "Tooltip",
        "content": "Top",
        "side": "top",
        "children": [
          {
            "type": "Button",
            "label": "Top",
            "variant": "outline",
            "size": "default",
            "disabled": false
          }
        ]
      },
      {
        "type": "Tooltip",
        "content": "Right",
        "side": "right",
        "children": [
          {
            "type": "Button",
            "label": "Right",
            "variant": "outline",
            "size": "default",
            "disabled": false
          }
        ]
      },
      {
        "type": "Tooltip",
        "content": "Bottom",
        "side": "bottom",
        "children": [
          {
            "type": "Button",
            "label": "Bottom",
            "variant": "outline",
            "size": "default",
            "disabled": false
          }
        ]
      },
      {
        "type": "Tooltip",
        "content": "Left",
        "side": "left",
        "children": [
          {
            "type": "Button",
            "label": "Left",
            "variant": "outline",
            "size": "default",
            "disabled": false
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Instant Tooltips

By default, tooltips wait 700ms before appearing. Set `delay=0` for immediate feedback — useful in dashboards or status displays where users are scanning quickly.

<ComponentPreview height="140px" json={{"view":{"cssClass":"gap-4","type":"Row","children":[{"type":"Tooltip","content":"Deployed 2h ago","delay":0,"children":[{"type":"Badge","label":"In Orbit","variant":"default"}]},{"type":"Tooltip","content":"64% \u2014 ETA 12 min","delay":0,"children":[{"type":"Badge","label":"Deploying","variant":"secondary"}]},{"type":"Tooltip","content":"Position 3 of 8","delay":0,"children":[{"type":"Badge","label":"Queued","variant":"outline"}]}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQmFkZ2UsIFJvdywgVG9vbHRpcAoKd2l0aCBSb3coZ2FwPTQpOgogICAgd2l0aCBUb29sdGlwKCJEZXBsb3llZCAyaCBhZ28iLCBkZWxheT0wKToKICAgICAgICBCYWRnZSgiSW4gT3JiaXQiKQogICAgd2l0aCBUb29sdGlwKCI2NCUg4oCUIEVUQSAxMiBtaW4iLCBkZWxheT0wKToKICAgICAgICBCYWRnZSgiRGVwbG95aW5nIiwgdmFyaWFudD0ic2Vjb25kYXJ5IikKICAgIHdpdGggVG9vbHRpcCgiUG9zaXRpb24gMyBvZiA4IiwgZGVsYXk9MCk6CiAgICAgICAgQmFkZ2UoIlF1ZXVlZCIsIHZhcmlhbnQ9Im91dGxpbmUiKQo=">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Badge, Row, Tooltip

with Row(gap=4):
    with Tooltip("Deployed 2h ago", delay=0):
        Badge("In Orbit")
    with Tooltip("64% — ETA 12 min", delay=0):
        Badge("Deploying", variant="secondary")
    with Tooltip("Position 3 of 8", delay=0):
        Badge("Queued", variant="outline")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Row",
    "children": [
      {
        "type": "Tooltip",
        "content": "Deployed 2h ago",
        "delay": 0,
        "children": [{"type": "Badge", "label": "In Orbit", "variant": "default"}]
      },
      {
        "type": "Tooltip",
        "content": "64% \u2014 ETA 12 min",
        "delay": 0,
        "children": [{"type": "Badge", "label": "Deploying", "variant": "secondary"}]
      },
      {
        "type": "Tooltip",
        "content": "Position 3 of 8",
        "delay": 0,
        "children": [{"type": "Badge", "label": "Queued", "variant": "outline"}]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## API Reference

<Card icon="code" title="Tooltip Parameters">
<ParamField body="content" type="str" required>
  Tooltip text. Can be passed as a positional argument.
</ParamField>

<ParamField body="side" type="str | None" default="None">
  Which side to show the tooltip: `"top"`, `"right"`, `"bottom"`, `"left"`.
</ParamField>

<ParamField body="delay" type="int | None" default="None">
  Delay in milliseconds before showing the tooltip. Defaults to 700ms. Set to `0` for instant display.
</ParamField>

<ParamField body="css_class" type="str | None" default="None">
  Additional Tailwind CSS classes.
</ParamField>
</Card>

## Protocol Reference

```json Tooltip
{
  "type": "Tooltip",
  "children?": "[Component]",
  "let?": "object",
  "content": "string (required)",
  "side?": "top | right | bottom | left",
  "delay?": "number",
  "cssClass?": "string"
}
```

For the complete protocol schema, see [Tooltip](/protocol/tooltip).
