import {
  Canvas,
  Controls,
  Meta,
  Subtitle,
  Title,
} from '@storybook/addon-docs/blocks'
import * as TooltipStories from './Tooltip.stories'
import { LifecycleTag, SourceLinks } from '../../docs/components'

<Meta of={TooltipStories} />

<Title>Tooltip</Title>
<Subtitle>
  Floating label that appears on hover or focus to provide supplementary
  information about a trigger element.
</Subtitle>
<SourceLinks
  links={[
    {
      label: 'Radix UI',
      href: 'https://www.radix-ui.com/primitives/docs/components/tooltip',
    },
    {
      label: 'shadcn/ui',
      href: 'https://ui.shadcn.com/docs/components/tooltip',
    },
  ]}
/>
<LifecycleTag variant="Stable" />
**Component type:** Primitive

<Canvas of={TooltipStories.Default} sourceState="shown" />
<Controls of={TooltipStories.Default} />

## When to use

Use `Tooltip` only when your product is **desktop-only** and you do not need touch support. It shows on hover and does not work on mobile (no tap interaction).

If there is any chance the tooltip will be used on a touch device, use `ResponsiveTooltip` instead — it is the default choice for most products. Use `InfoTooltip` for a pre-built information icon trigger.

## Import

```tsx
import {
  Tooltip,
  TooltipProvider,
  TooltipTrigger,
  TooltipContent,
  TooltipArrow,
} from '@chainlink/blocks'
```

## Anatomy

```tsx
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <Button variant="ghost" size="sm">
        More info
      </Button>
    </TooltipTrigger>
    <TooltipContent>
      Helpful information here.
      <TooltipArrow />
    </TooltipContent>
  </Tooltip>
</TooltipProvider>
```

## Subcomponents

- `TooltipProvider`: Context provider required at the root. Sets the default hover delay for all tooltips in its subtree. Place once near the app root or around the tooltip group.
- `Tooltip`: Root state container for a single tooltip. Must be inside `TooltipProvider`.
- `TooltipTrigger`: The element that shows the tooltip on hover/focus. Use `asChild` to make any element the trigger.
- `TooltipContent`: Floating label that appears above/below the trigger. Renders in a portal. Accepts `side` and `align`.
- `TooltipArrow`: Optional pointer arrow inside `TooltipContent` pointing toward the trigger.

## Rendered Element

`TooltipContent` renders in a portal to ensure correct z-index stacking regardless of where `Tooltip` is placed in the DOM.

## Using asChild

`TooltipTrigger` renders a `<button>` by default. Use `asChild` to attach tooltip behavior to any element without adding an extra DOM node:

```tsx
<TooltipTrigger asChild>
  <span>Hover me</span>
</TooltipTrigger>
```

## Examples

### All sides

<Canvas of={TooltipStories.AllSides} sourceState="shown" />

### All alignments

<Canvas of={TooltipStories.AllAlignments} sourceState="shown" />

### No arrow

<Canvas of={TooltipStories.NoArrow} sourceState="shown" />

### Custom trigger

<Canvas of={TooltipStories.CustomTrigger} sourceState="shown" />

### Long content

<Canvas of={TooltipStories.LongContent} sourceState="shown" />

### With delay

<Canvas of={TooltipStories.WithDelay} sourceState="shown" />

## Related components

- `ResponsiveTooltip` for tooltips that must also work on mobile via tap
- `InfoTooltip` for a pre-built information icon trigger
- `Popover` for larger floating content that the user interacts with