A floating label that appears on hover or keyboard focus. Uses fixed positioning to escape overflow containers, with viewport clamping so it never leaves the screen.
Wrap any element with the tooltip component and pass a text prop. Hover or focus the trigger to reveal it.
<x-ui::tooltip text="This is a tooltip">
<x-ui::button>Hover me</x-ui::button>
</x-ui::tooltip>Four positions — top (default), bottom, left, right. The tooltip is clamped to the viewport so it never goes off-screen.
<x-ui::tooltip text="Top tooltip" position="top">
<x-ui::button variant="secondary">Top</x-ui::button>
</x-ui::tooltip>
<x-ui::tooltip text="Bottom tooltip" position="bottom">
<x-ui::button variant="secondary">Bottom</x-ui::button>
</x-ui::tooltip>
<x-ui::tooltip text="Left tooltip" position="left">
<x-ui::button variant="secondary">Left</x-ui::button>
</x-ui::tooltip>
<x-ui::tooltip text="Right tooltip" position="right">
<x-ui::button variant="secondary">Right</x-ui::button>
</x-ui::tooltip>dark (default) uses a near-black background. light uses a white background with a subtle ring — better on dark page sections.
{{-- Dark (default) --}}
<x-ui::tooltip text="Dark tooltip" variant="dark">
<x-ui::button variant="secondary">Dark</x-ui::button>
</x-ui::tooltip>
{{-- Light --}}
<x-ui::tooltip text="Light tooltip" variant="light">
<x-ui::button variant="secondary">Light</x-ui::button>
</x-ui::tooltip>Tooltips work on any element — icons, badges, avatars, text, or disabled buttons.
{{-- On an icon --}}
<x-ui::tooltip text="Settings" position="bottom">
<x-ui::icon name="cog-6-tooth" class="w-5 h-5 text-zinc-500 cursor-pointer hover:text-zinc-700" />
</x-ui::tooltip>
{{-- On a badge --}}
<x-ui::tooltip text="3 unread messages" position="bottom">
<x-ui::badge color="red">3</x-ui::badge>
</x-ui::tooltip>
{{-- On an avatar --}}
<x-ui::tooltip text="Jane Doe · Admin" position="bottom">
<x-ui::avatar name="Jane Doe" size="sm" />
</x-ui::tooltip>
{{-- On a disabled button --}}
<x-ui::tooltip text="You need admin access" position="bottom">
<span class="inline-block cursor-not-allowed">
<x-ui::button variant="primary" disabled>Restricted</x-ui::button>
</span>
</x-ui::tooltip>A common pattern — icon-only action buttons where tooltips provide the accessible label for each action.
<div class="flex items-center gap-1 rounded-xl border border-gray-200 dark:border-zinc-700 bg-white dark:bg-zinc-900 p-1">
<x-ui::tooltip text="Bold" position="bottom">
<x-ui::button variant="ghost" size="icon">
<x-ui::icon name="bold" variant="solid" class="w-4 h-4" />
</x-ui::button>
</x-ui::tooltip>
<x-ui::tooltip text="Italic" position="bottom">
<x-ui::button variant="ghost" size="icon">
<x-ui::icon name="italic" variant="solid" class="w-4 h-4" />
</x-ui::button>
</x-ui::tooltip>
<x-ui::tooltip text="Underline" position="bottom">
<x-ui::button variant="ghost" size="icon">
<x-ui::icon name="underline" variant="solid" class="w-4 h-4" />
</x-ui::button>
</x-ui::tooltip>
<x-ui::separator />
<x-ui::tooltip text="Insert link" position="bottom">
<x-ui::button variant="ghost" size="icon">
<x-ui::icon name="link" class="w-4 h-4" />
</x-ui::button>
</x-ui::tooltip>
<x-ui::tooltip text="Insert image" position="bottom">
<x-ui::button variant="ghost" size="icon">
<x-ui::icon name="photo" class="w-4 h-4" />
</x-ui::button>
</x-ui::tooltip>
<x-ui::tooltip text="Insert code block" position="bottom">
<x-ui::button variant="ghost" size="icon">
<x-ui::icon name="code-bracket" class="w-4 h-4" />
</x-ui::button>
</x-ui::tooltip>
</div>Place a tooltip on a help icon next to a form label to give contextual guidance without cluttering the UI.
<div class="space-y-5">
<div class="space-y-1.5">
<div class="flex items-center gap-1.5">
<label class="text-sm font-medium text-gray-700 dark:text-gray-300">API Key</label>
<x-ui::tooltip
text="Your API key grants full access. Never share it publicly."
position="right"
variant="light"
>
<x-ui::icon name="question-mark-circle" class="w-4 h-4 text-zinc-400 cursor-help" />
</x-ui::tooltip>
</div>
<x-ui::input name="api_key" type="password" placeholder="sk-••••••••••••••••" />
</div>
<div class="space-y-1.5">
<div class="flex items-center gap-1.5">
<label class="text-sm font-medium text-gray-700 dark:text-gray-300">Webhook URL</label>
<x-ui::tooltip
text="We will POST a JSON payload to this URL on each event."
position="right"
variant="light"
>
<x-ui::icon name="question-mark-circle" class="w-4 h-4 text-zinc-400 cursor-help" />
</x-ui::tooltip>
</div>
<x-ui::input name="webhook_url" placeholder="https://example.com/webhook" />
</div>
</div>