Tooltip

A small hint that appears on hover or focus to label a control.

Usage

import { TooltipProvider, Tooltip, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'
import { Button } from '@appica/ui-react/button'

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger
      render={
        <Button variant="outline" size="icon-md" aria-label="Add to favorites">
          <Heart />
        </Button>
      }
    />
    <TooltipContent>Add to favorites</TooltipContent>
  </Tooltip>
</TooltipProvider>

A tooltip is a short, non-interactive hint that appears when its trigger is hovered or focused — most often to name an icon-only control. The trigger is wired to the popup through render: pass it your own Button (or any focusable element) and the tooltip manages its description and open/close.

Tooltip is a compound component built on Base UI's Tooltip:

TooltipProvider — wraps a group of tooltips and shares the hover delay. Place one high in your app so that once one tooltip has opened, moving to a sibling shows its tooltip instantly instead of waiting out the delay again.
Tooltip — the root for a single tooltip. Holds its open state; set trackCursorAxis to follow the pointer or disabled to suppress it.
TooltipTrigger — the element the tooltip describes. Use render to project it onto your own control.
TooltipContent — the portalled, auto-positioned popup. Draws the bubble and the optional arrow, and accepts the shared floating props (side, align, sideOffset, …).

Tooltips aren't reachable on touch or by screen readers

A tooltip only appears on hover/focus, so its text is invisible on touch devices and isn't announced as the control's name. Always give an icon-only trigger its own aria-label (or visible text) — the tooltip is a visual nicety on top, not the accessible name. For content that must be reachable by everyone, use a Popover.

Reach for a Tooltip to label or hint at a control. For rich or interactive floating content, use a Popover; for a list of actions, use a Dropdown Menu; for a hover preview of a link, use a Preview Card.

Examples

Side & alignment

Position the bubble with side (top / right / bottom / left) and align (start / center / end) on TooltipContent. It flips and shifts automatically to stay in view.

import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'
import { Button } from '@appica/ui-react/button'

const SIDES = ['top', 'right', 'bottom', 'left'] as const

export default function TooltipSides() {
  return (
    <TooltipProvider>
      <div className="flex flex-wrap items-center justify-center gap-3">
        {SIDES.map((side) => (
          <Tooltip key={side}>
            <TooltipTrigger render={<Button variant="outline">{side}</Button>} />
            <TooltipContent side={side}>Opens on the {side}</TooltipContent>
          </Tooltip>
        ))}
      </div>
    </TooltipProvider>
  )
}

Shared provider

Wrap a group of controls — here a Toolbar of formatting buttons — in a single TooltipProvider. The first tooltip waits out the delay; once it's open, sweeping the pointer to a neighbour shows that tooltip immediately. Within that grace window the tooltip also skips its open/close animation, so it reads as one tooltip relocating across the toolbar rather than each popup re-bouncing.

import * as React from 'react'
import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'
import { Toolbar, ToolbarButton, ToolbarSeparator } from '@appica/ui-react/toolbar'
import { Button } from '@appica/ui-react/button'
import { Bold, Italic, Underline, Strikethrough, Link } from '@appica/icons-react'

const ACTIONS = [
  { label: 'Bold', Icon: Bold },
  { label: 'Italic', Icon: Italic },
  { label: 'Underline', Icon: Underline },
  { label: 'Strikethrough', Icon: Strikethrough },
  { label: 'Link', Icon: Link },
] as const

export default function TooltipProviderDemo() {
  return (
    <TooltipProvider delay={400}>
      <Toolbar aria-label="Text formatting">
        {ACTIONS.map(({ label, Icon }, index) => (
          <React.Fragment key={label}>
            {index === ACTIONS.length - 1 && <ToolbarSeparator />}
            <Tooltip>
              <TooltipTrigger
                render={
                  <ToolbarButton
                    render={
                      <Button variant="ghost" size="icon-md" aria-label={label}>
                        <Icon />
                      </Button>
                    }
                  />
                }
              />
              <TooltipContent>{label}</TooltipContent>
            </Tooltip>
          </React.Fragment>
        ))}
      </Toolbar>
    </TooltipProvider>
  )
}

Rich content

TooltipContent accepts any markup, so you can pair a label with a Kbd shortcut. Keep it terse and non-interactive — the popup closes as soon as the pointer leaves the trigger.

import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'
import { Button } from '@appica/ui-react/button'
import { Kbd } from '@appica/ui-react/kbd'
import { Bookmark } from '@appica/icons-react'

export default function TooltipShortcut() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger
          render={
            <Button variant="outline" size="icon-md" aria-label="Save">
              <Bookmark />
            </Button>
          }
        />
        <TooltipContent className="flex items-center gap-2">
          Save
          <Kbd size="sm">⌘ S</Kbd>
        </TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

Follow the cursor

Set trackCursorAxis on the Tooltip to 'x', 'y', or 'both' so the bubble follows the pointer along that axis — handy over a wide target like a chart or canvas where a fixed anchor would feel disconnected.

Hover and move across

import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'

export default function TooltipTrackCursor() {
  return (
    <TooltipProvider>
      <Tooltip trackCursorAxis="x">
        <TooltipTrigger
          render={
            <div className="bg-background-subtle border-border-strong flex h-32 w-72 items-center justify-center rounded-xl border border-dashed text-sm select-none">
              Hover and move across
            </div>
          }
        />
        <TooltipContent>Following the cursor</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

Without an arrow

Pass arrow={false} to drop the pointer for a flatter bubble that sits flush against its offset.

import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@appica/ui-react/tooltip'
import { Button } from '@appica/ui-react/button'

export default function TooltipNoArrow() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline">No arrow</Button>} />
        <TooltipContent arrow={false}>Sits flush, without a pointer</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware placement follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

start/end alignment mirrors with the document direction. For setup details and caveats, see the RTL guide.

Scoped RTL needs the direction on the positioner

The popup portals to <body>, so its start/end alignment mirrors from the document direction (read from CSS, not from DirectionProvider) — automatic when <html dir="rtl">. If you instead scope RTL to a subtree of an LTR page, set it on the positioner so alignment still mirrors: <TooltipContent positionerProps={{ dir: 'rtl' }}>. See Floating popups in a scoped RTL region.

API reference

Tooltip wraps Base UI's Tooltip. Each part forwards every remaining prop to the matching Base UI primitive, so anything it accepts works here — the tables below list the Appica additions and the most common props. See the Base UI docs for the complete API.

TooltipProvider

Shares the hover delay across the tooltips it wraps. Renders no DOM of its own.

Prop	Type	Default	Description
`delay`	`number`	`200`	Hover-open delay in ms applied to every tooltip inside.
`closeDelay`	`number`	`0`	Hover-close delay in ms.
`timeout`	`number`	`400`	Window after a tooltip closes during which the next one opens instantly (no delay).

The root for a single tooltip. Holds the open state; renders no DOM of its own.

Prop	Type	Default	Description
`open`	`boolean`	—	Controlled open state. Pair with `onOpenChange`.
`defaultOpen`	`boolean`	`false`	Uncontrolled initial open state.
`onOpenChange`	`(open, eventDetails) => void`	—	Fires when the tooltip opens or closes.
`trackCursorAxis`	`'none' \| 'x' \| 'y' \| 'both'`	`'none'`	Make the bubble follow the cursor along the given axis.
`disabled`	`boolean`	`false`	Prevent the tooltip from opening.
`delay`	`number`	—	Override the provider's hover-open delay for this tooltip.
`closeDelay`	`number`	—	Override the provider's hover-close delay for this tooltip.

TooltipTrigger

The element the tooltip describes. Forwards Base UI's Tooltip.Trigger; use render to project it onto your own control.

Prop	Type	Default	Description
`render`	`ReactElement \| (props, state) => ReactElement`	—	Render the trigger as your own element (e.g. a `Button`).
`className`	`string`	—	Extra classes on the trigger, merged via `tailwind-merge`.

TooltipContent

The portalled, auto-positioned bubble. Draws the popup and the optional arrow, and accepts the shared floating props. Defaults to side="top", align="center", and sideOffset={8} (or 4 without an arrow).

Prop	Type	Default	Description
`arrow`	`boolean`	`true`	Render the pointer.
`side`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'top'`	Preferred side to open on.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Alignment along that side.
`sideOffset`	`number`	`8`	Gap between the trigger and the bubble.
`alignOffset`	`number`	`0`	Shift along the alignment axis.
`collisionPadding`	`number`	`5`	Minimum gap kept from the viewport edge when flipping/shifting.
`anchor`	`Element \| ref \| VirtualElement`	—	Anchor against a different element than the trigger.
`container`	`HTMLElement \| ref \| null`	—	Portal target — render the popup into a different node.
`positionerProps`	`object`	—	Escape hatch for the positioner element (`style`, `render`, `dir`, …).
`portalProps`	`object`	—	Escape hatch for the portal element (`style`, `render`, …).
`className`	`string`	—	Extra classes on the bubble.

Accessibility

The popup is wired to the trigger via aria-describedby, so screen readers announce it as a description — not the control's name. Give icon-only triggers an aria-label (or visible text) of their own.
The tooltip opens on hover and keyboard focus, and closes on Escape, on blur, or when the pointer leaves.
Tooltips don't open on touch — there's no hover — so never hide essential information in one.
Within a TooltipProvider, the delay is shared and subsequent tooltips open instantly within the timeout window.
Enter/exit transitions are skipped when the user prefers reduced motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback

Tooltip

Usage

Tooltips aren't reachable on touch or by screen readers

Examples

Side & alignment

Shared provider

Rich content

Follow the cursor

Without an arrow

RTL

Scoped RTL needs the direction on the positioner

API reference

TooltipProvider

Tooltip

TooltipTrigger

TooltipContent

Accessibility