> ## Documentation Index
> Fetch the complete documentation index at: https://araf.badr.co.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Tooltip

> A small floating label that appears on hover or focus to provide contextual information about an element.

## Overview

<div style={{display:"flex",gap:"24px",flexWrap:"wrap",padding:"28px 24px",background:"#f9fafb",borderRadius:"12px",border:"1px solid #e5e7eb",alignItems:"flex-end"}}>
  <div style={{display:"flex",flexDirection:"column",alignItems:"center",gap:"6px"}}>
    <div style={{background:"#18181B",color:"#fff",borderRadius:"6px",padding:"5px 10px",fontSize:"12px",fontWeight:500,fontFamily:"Inter,sans-serif",whiteSpace:"nowrap",position:"relative"}}>
      Delete item

      <div style={{position:"absolute",bottom:"-4px",left:"50%",transform:"translateX(-50%)",width:"8px",height:"4px",background:"#18181B",clipPath:"polygon(0 0, 100% 0, 50% 100%)"}} />
    </div>

    <button style={{padding:"8px",borderRadius:"6px",border:"1px solid #E4E4E7",background:"#fff",cursor:"pointer",display:"flex",alignItems:"center",justifyContent:"center"}}>
      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#71717A" strokeWidth="2">
        <polyline points="3 6 5 6 21 6" />

        <path d="M19 6l-1 14H6L5 6" />
      </svg>
    </button>

    <span style={{fontSize:"11px",color:"#71717a",fontFamily:"Inter,sans-serif"}}>Top (default)</span>
  </div>

  <div style={{display:"flex",alignItems:"center",gap:"6px"}}>
    <button style={{padding:"8px 14px",borderRadius:"6px",border:"1px solid #E4E4E7",background:"#fff",cursor:"pointer",fontSize:"13px",fontFamily:"Inter,sans-serif",color:"#344054"}}>Hover me</button>

    <div style={{background:"#18181B",color:"#fff",borderRadius:"6px",padding:"5px 10px",fontSize:"12px",fontWeight:500,fontFamily:"Inter,sans-serif",whiteSpace:"nowrap",position:"relative"}}>
      <div style={{position:"absolute",left:"-4px",top:"50%",transform:"translateY(-50%)",width:"4px",height:"8px",background:"#18181B",clipPath:"polygon(100% 0, 100% 100%, 0 50%)"}} />

      Appears on the right
    </div>
  </div>
</div>

**Tooltip** shows brief text on hover or focus. Use it to clarify icon buttons, explain truncated content, or surface keyboard shortcuts. Tooltips auto-position to stay visible within the viewport.

***

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @araf-ds/core
  ```

  ```bash yarn theme={null}
  yarn add @araf-ds/core
  ```

  ```bash pnpm theme={null}
  pnpm add @araf-ds/core
  ```
</CodeGroup>

***

## Usage

```tsx theme={null}
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@araf-ds/core"

export default function Example() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <Button variant="ghost" size="icon">
            <TrashIcon size={16} />
          </Button>
        </TooltipTrigger>
        <TooltipContent>Delete item</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}
```

***

## Variants

### Basic

<div style={{padding:"24px",background:"#f9fafb",borderRadius:"12px",border:"1px solid #e5e7eb",display:"flex",justifyContent:"center",alignItems:"flex-end",gap:"0",flexDirection:"column",alignItems:"center",gap:"6px"}}>
  <div style={{background:"#18181B",color:"#fff",borderRadius:"6px",padding:"5px 10px",fontSize:"12px",fontWeight:500,fontFamily:"Inter,sans-serif",position:"relative"}}>
    Delete item

    <div style={{position:"absolute",bottom:"-4px",left:"50%",transform:"translateX(-50%)",width:"8px",height:"4px",background:"#18181B",clipPath:"polygon(0 0, 100% 0, 50% 100%)"}} />
  </div>

  <button style={{padding:"8px",borderRadius:"6px",border:"1px solid #E4E4E7",background:"#fff",cursor:"pointer",display:"flex",alignItems:"center",justifyContent:"center",marginTop:"4px"}}>
    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#71717A" strokeWidth="2">
      <polyline points="3 6 5 6 21 6" />

      <path d="M19 6l-1 14H6L5 6" />
    </svg>
  </button>
</div>

```tsx theme={null}
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <Button variant="ghost" size="icon">
        <TrashIcon size={16} />
      </Button>
    </TooltipTrigger>
    <TooltipContent>Delete item</TooltipContent>
  </Tooltip>
</TooltipProvider>
```

### Placement

<div style={{padding:"24px",background:"#f9fafb",borderRadius:"12px",border:"1px solid #e5e7eb"}}>
  <div style={{display:"flex",gap:"16px",alignItems:"center",flexWrap:"wrap",justifyContent:"center"}}>
    {["Top","Bottom","Left","Right"].map((side) => (
            <div key={side} style={{display:"flex",flexDirection:"column",alignItems:"center",gap:"4px"}}>
              <span style={{fontSize:"11px",color:"#71717a",fontFamily:"Inter,sans-serif"}}>{side}</span>
              <div style={{background:"#18181B",color:"#fff",borderRadius:"6px",padding:"4px 8px",fontSize:"11px",fontFamily:"Inter,sans-serif"}}>{side}</div>
            </div>
          ))}
  </div>
</div>

```tsx theme={null}
<TooltipContent side="top">Tooltip above</TooltipContent>
<TooltipContent side="bottom">Tooltip below</TooltipContent>
<TooltipContent side="left">Tooltip left</TooltipContent>
<TooltipContent side="right">Tooltip right</TooltipContent>
```

### With Keyboard Shortcut

<div style={{padding:"24px",background:"#f9fafb",borderRadius:"12px",border:"1px solid #e5e7eb",display:"flex",flexDirection:"column",alignItems:"center",gap:"6px"}}>
  <div style={{background:"#18181B",color:"#fff",borderRadius:"6px",padding:"5px 10px",fontSize:"12px",fontWeight:500,fontFamily:"Inter,sans-serif",display:"flex",alignItems:"center",gap:"6px",position:"relative"}}>
    Save
    <span style={{background:"rgba(255,255,255,0.2)",borderRadius:"4px",padding:"1px 5px",fontSize:"11px",fontFamily:"Inter,sans-serif"}}>⌘S</span>

    <div style={{position:"absolute",bottom:"-4px",left:"50%",transform:"translateX(-50%)",width:"8px",height:"4px",background:"#18181B",clipPath:"polygon(0 0, 100% 0, 50% 100%)"}} />
  </div>

  <button style={{padding:"8px",borderRadius:"6px",border:"1px solid #E4E4E7",background:"#fff",cursor:"pointer",display:"flex",alignItems:"center",justifyContent:"center",marginTop:"4px"}}>
    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#71717A" strokeWidth="2">
      <path d="M19 21H5a2 2 0 01-2-2V5a2 2 0 012-2h11l5 5v11a2 2 0 01-2 2z" />

      <polyline points="17 21 17 13 7 13 7 21" />

      <polyline points="7 3 7 8 15 8" />
    </svg>
  </button>
</div>

```tsx theme={null}
<Tooltip>
  <TooltipTrigger asChild>
    <Button variant="ghost" size="icon"><SaveIcon size={16} /></Button>
  </TooltipTrigger>
  <TooltipContent>
    Save <kbd className="ml-1 rounded bg-white/20 px-1 text-xs">⌘S</kbd>
  </TooltipContent>
</Tooltip>
```

***

## API Reference

### Tooltip (Root)

<ParamField path="open" type="boolean">
  Controlled open state.
</ParamField>

<ParamField path="onOpenChange" type="(open: boolean) => void">
  Callback fired when the open state changes.
</ParamField>

<ParamField path="defaultOpen" type="boolean" default="false">
  Uncontrolled default open state.
</ParamField>

<ParamField path="delayDuration" type="number" default="400">
  Hover delay before the tooltip appears (ms).
</ParamField>

### TooltipContent

<ParamField path="side" type="string" default="top">
  Preferred placement. Values: `top` · `bottom` · `left` · `right`
</ParamField>

<ParamField path="sideOffset" type="number" default="4">
  Distance from the trigger in pixels.
</ParamField>

<ParamField path="align" type="string" default="center">
  Alignment along the placement axis. Values: `start` · `center` · `end`
</ParamField>

<ParamField path="size" type="string" default="md">
  Tooltip size. Values: `sm` · `md`
</ParamField>

<ParamField path="className" type="string">
  Additional Tailwind classes for custom overrides.
</ParamField>

***

## Accessibility

* Tooltip content uses `role="tooltip"` with a unique `id`
* The trigger has `aria-describedby` pointing to the tooltip `id`
* Tooltip opens on hover AND keyboard focus — never only on hover
* Pressing Escape dismisses the tooltip
* Do not put interactive elements (links, buttons) inside tooltip content

***

## Do's & Don'ts

<CardGroup cols={2}>
  <Card title="Do" icon="check" iconType="solid" color="#16A34A">
    * Use Tooltip to label icon-only buttons
    * Keep tooltip text to one short sentence or a keyboard shortcut
    * Use `side="bottom"` for elements at the top of the viewport
    * Always make the tooltip trigger keyboard-focusable
  </Card>

  <Card title="Don't" icon="xmark" iconType="solid" color="#DC2626">
    * Don't put interactive elements (links, buttons) inside tooltips
    * Don't use Tooltip to hide essential information — it must be discoverable
    * Don't use Tooltip for mobile-only touch targets — hover doesn't work on touch
    * Don't add long paragraphs — use a Popover for rich content
  </Card>
</CardGroup>