How to Use

Tooltip

Tooltip displays a small label on hover or focus. Wrap any interactive element with Tooltip to provide additional context. The content prop is the text shown. The placement prop controls position (top, bottom, left, right). The color prop changes the tooltip background for semantic hints (success, warning, danger). Tooltips appear after a short delay and disappear on mouse leave or blur. Use them to clarify icon-only buttons, show truncated text values, or provide hints without cluttering the interface.

import {Tooltip} from "oks-ui"

Icon Button Labels

The most common use case: wrap icon-only buttons with Tooltip so users understand what the icon means. The content prop is a short text label. Always wrap icon-only buttons with Tooltip — without it, users cannot determine the button's purpose. The tooltip appears above the button by default (placement="top"). Use different colors for different actions — danger for delete, primary for settings.

<div className="flex items-center gap-4">
  <Tooltip content="Edit user">
    <Button isIconOnly variant="soft" aria-label="Edit">
      <span>✏</span>
    </Button>
  </Tooltip>
  <Tooltip content="Delete user" color="danger">
    <Button isIconOnly variant="soft" aria-label="Delete">
      <span>🗑</span>
    </Button>
  </Tooltip>
  <Tooltip content="Settings" color="primary">
    <Button isIconOnly variant="soft" aria-label="Settings">
      <span>⚙</span>
    </Button>
  </Tooltip>
</div>

Placement

The placement prop controls where the tooltip appears: "top" (above the element, centered), "bottom" (below, centered), "left" (to the left, middle), "right" (to the right, middle). The tooltip automatically flips to the opposite side if there isn't enough space in the viewport. Default is "top". Choose placement based on surrounding content — avoid covering important UI with the tooltip.

<div className="flex flex-wrap items-center gap-4">
  <Tooltip content="Top" placement="top">
    <Button variant="soft" size="sm">Top</Button>
  </Tooltip>
  <Tooltip content="Bottom" placement="bottom">
    <Button variant="soft" size="sm">Bottom</Button>
  </Tooltip>
  <Tooltip content="Left" placement="left">
    <Button variant="soft" size="sm">Left</Button>
  </Tooltip>
  <Tooltip content="Right" placement="right">
    <Button variant="soft" size="sm">Right</Button>
  </Tooltip>
</div>

Color Variants

The color prop changes the tooltip's background and text colors. Use semantic colors to add meaning: color="success" for positive hints ("Available"), color="warning" for cautionary hints ("Limited stock"), color="danger" for destructive hints ("Delete forever"), color="primary" for neutral informational hints. The default color (no color prop) uses neutral tones.

<div className="flex items-center gap-4">
  <Tooltip content="Online" color="success">
    <span className="block h-3 w-3 rounded-full bg-green-500" />
  </Tooltip>
  <Tooltip content="Away" color="warning">
    <span className="block h-3 w-3 rounded-full bg-amber-500" />
  </Tooltip>
  <Tooltip content="Offline" color="danger">
    <span className="block h-3 w-3 rounded-full bg-red-500" />
  </Tooltip>
</div>

Accessibility

Tooltip uses role="tooltip" and is connected to its trigger element via aria-describedby. The tooltip appears on both hover (mouse) and focus (keyboard). This means keyboard users and screen reader users also benefit from tooltip content. The delay before showing (typically 300ms) prevents flickering when users quickly move the mouse across elements. The tooltip disappears when the trigger loses hover or focus. Keep tooltip text short — 1-5 words maximum. For longer explanations, use inline help text or a Popover component instead. Screen readers will read the tooltip content when the trigger element receives focus.

Props Reference

All available props for Tooltip. See the full API reference page for interactive playground examples.

Prop	Type	Default	Description
content	ReactNode	`—`	Tooltip content (required).
placement	"top" \| "bottom" \| "left" \| "right" \| "top-start" \| "top-end" \| "bottom-start" \| "bottom-end" \| "left-start" \| "left-end" \| "right-start" \| "right-end"	`"top"`	Tooltip placement.
color	"default" \| "primary" \| "secondary" \| "info" \| "success" \| "warning" \| "danger"	`"default"`	Tooltip color.
size	"xs" \| "xs-sm" \| "sm" \| "md" \| "lg" \| "xl"	`"md"`	Tooltip size.
delay	number	`0`	Show delay in ms.
closeDelay	number	`0`	Hide delay in ms.
showArrow	boolean	`true`	Show arrow pointer.
shouldFlip	boolean	`true`	Flip to stay in viewport.
offset	number	`7`	Offset from the trigger element.

Best Practices

◆Always wrap icon-only buttons with Tooltip — without it, users (especially those with cognitive disabilities) cannot determine the button's purpose
◆Use placement="top" as the default — it's the most natural reading position and least likely to cover important content
◆Tooltips work on focus too — important for keyboard users and screen reader compatibility
◆Keep tooltip text very short (1-5 words). For longer explanations, use inline help text below the element or a Popover
◆Use color="danger" for destructive action hints ("Delete", "Remove"), color="primary" for general hints
◆Do not put interactive content (buttons, links) inside Tooltips — they are not meant for interaction, only information

View full API reference for Tooltip →