Components

Tooltip

A short label that appears beside a control on hover or keyboard focus, built on Base UI's tooltip primitive.

Import

import { Tooltip } from '@oztix/roadie-components/tooltip'

Examples

Default

Pass the control to Tooltip.Trigger with render. The control keeps its own accessible name. Here that is the icon button's aria-label. The tooltip repeats it for pointer users.

<Tooltip>
  <Tooltip.Trigger render={<IconButton aria-label='Edit'><PencilSimple weight='bold' className='size-4' /></IconButton>} />
  <Tooltip.Content>
    <Tooltip.Arrow />
    Edit
  </Tooltip.Content>
</Tooltip>

Side

side places the tooltip. Beside a vertical toolbar, prefer inline-start and inline-end so the placement follows the reading direction.

<div className='flex flex-wrap gap-3'>
  {['top', 'bottom', 'inline-start', 'inline-end'].map((side) => (
    <Tooltip key={side}>
      <Tooltip.Trigger render={<Button>{side}</Button>} />
      <Tooltip.Content side={side}>
        <Tooltip.Arrow />
        Placed {side}
      </Tooltip.Content>
    </Tooltip>
  ))}
</div>

Emphasis

strong is the default high-contrast chip, neutral unless you give it an intent. The tooltip renders in a portal, outside the page's intent context, so put the intent class on Tooltip.Content. Use floating, the same surface as a popover, over dark or busy content where a dark chip would disappear.

<div className='flex flex-wrap gap-3'>
  <Tooltip>
    <Tooltip.Trigger render={<Button>Strong</Button>} />
    <Tooltip.Content>
      <Tooltip.Arrow />
      Strong
    </Tooltip.Content>
  </Tooltip>
  <Tooltip>
    <Tooltip.Trigger render={<Button>Strong, accent</Button>} />
    <Tooltip.Content className='intent-accent'>
      <Tooltip.Arrow />
      Strong, accent
    </Tooltip.Content>
  </Tooltip>
  <Tooltip>
    <Tooltip.Trigger render={<Button>Floating</Button>} />
    <Tooltip.Content emphasis='floating'>
      <Tooltip.Arrow />
      Floating
    </Tooltip.Content>
  </Tooltip>
</div>

Delay group

Wrap related controls in Tooltip.Provider. The first tooltip waits for the delay; moving to a neighbour while one is open shows it straight away.

<Tooltip.Provider>
  <div className='flex gap-2'>
    {[
      ['Edit', <PencilSimple weight='bold' className='size-4' />],
      ['Favourite', <Heart weight='bold' className='size-4' />],
      ['Settings', <Gear weight='bold' className='size-4' />],
      ['Delete', <Trash weight='bold' className='size-4' />]
    ].map(([label, icon]) => (
      <Tooltip key={label}>
        <Tooltip.Trigger render={<IconButton aria-label={label}>{icon}</IconButton>} />
        <Tooltip.Content>{label}</Tooltip.Content>
      </Tooltip>
    ))}
  </div>
</Tooltip.Provider>

Guidelines

Keep a tooltip to a label

<Tooltip.Trigger render={<IconButton aria-label='Edit'>…</IconButton>} />

Label icon-only controls. Give the control its own accessible name and let the tooltip repeat it.

<Tooltip.Content><Button>Undo</Button></Tooltip.Content>

Don’t

Don't put actions or essential detail in a tooltip. It can't be reached on touch and closes when the pointer leaves. Use a Popover.

Write for a glance

Keep it to a few words. A tooltip names or briefly clarifies. Sentence case, no full stop.

Don’t

Don't rely on it on touch screens. Touch has no hover, so a tap won't show it. Where a tooltip must never appear on touch, add className='pointer-coarse:hidden' to Tooltip.Content.

Accessibility

The tooltip isn't announced. The trigger carries its own name. That is an aria-label on an icon-only control, or visible or visually hidden text.
Keyboard focus opens the tooltip; Escape closes it.
Hover and focus only. Don't use a tooltip for anything a keyboard, screen reader or touch user needs.

API reference

Tooltip

defaultOpenboolean: Whether the tooltip is initially open. To render a controlled tooltip, use the `open` prop instead.
Defaults to false.
openboolean: Whether the tooltip is currently open.
onOpenChange((open: boolean, eventDetails: TooltipRootChangeEventDetails) => void): Event handler called when the tooltip is opened or closed.
onOpenChangeComplete((open: boolean) => void): Event handler called after any animations complete when the tooltip is opened or closed.
disableHoverablePopupboolean: Whether the tooltip contents can be hovered without closing the tooltip.
Defaults to false.
trackCursorAxis"none" | "both" | "x" | "y": Determines which axis the tooltip should track the cursor on.
Defaults to 'none'.
actionsRefRefObject<TooltipRootActions | null>: A ref to imperative actions. - `unmount`: Unmounts the tooltip popup. - `close`: Closes the tooltip imperatively when called.
disabledboolean: Whether the tooltip is disabled.
Defaults to false.
handleTooltipHandle<unknown>: A handle to associate the tooltip with a trigger. If specified, allows external triggers to control the tooltip's open state. Can be created with the Tooltip.createHandle() method.
childrenReactNode | PayloadChildRenderFunction<unknown>: The content of the tooltip. This can be a regular React node or a render function that receives the `payload` of the active trigger.
triggerIdstring | null: ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `open` prop to create a controlled tooltip. There's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set).
defaultTriggerIdstring | null: ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip.

Tooltip.Arrow

No additional props. It forwards all standard HTML attributes to the underlying element.

Tooltip.Content

classNamestring | ((state: TooltipPopupState) => string): CSS class applied to the element, or a function that returns a class based on the component's state.
emphasis"strong" | "floating": Portaled, so colour `strong` with an intent class here.
Defaults to 'strong'.
side"top" | "bottom" | "left" | "right" | "inline-start" | "inline-end": Defaults to 'top'.
align"center" | "start" | "end": Defaults to 'center'.
sideOffsetnumber: Gap between trigger and tooltip, in px.
Defaults to 6.
alignOffsetnumber: Shift along the trigger's edge, in px.
Defaults to 0.

Tooltip.Popup

classNamestring | ((state: TooltipPopupState) => string): CSS class applied to the element, or a function that returns a class based on the component's state.
emphasis"strong" | "floating": Portaled, so colour `strong` with an intent class here.
Defaults to 'strong'.

Tooltip.Portal

classNamestring | ((state: TooltipPortalState) => string): CSS class applied to the element, or a function that returns a class based on the component's state.

Inherited from TooltipPortalProps

keepMountedboolean: Whether to keep the portal mounted in the DOM while the popup is hidden.
Defaults to false.
containerHTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null: A parent element to render the portal element into.

Tooltip.Positioner

classNamestring | ((state: TooltipPositionerState) => string): CSS class applied to the element, or a function that returns a class based on the component's state.

Inherited from TooltipPositionerProps

side"top" | "bottom" | "left" | "right" | "inline-start" | "inline-end": Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
Defaults to 'top'.

Inherited from UseAnchorPositioningSharedParameters

align"center" | "start" | "end": How to align the popup relative to the specified side.
Defaults to 'center'.
sideOffsetnumber | OffsetFunction: Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side. @example ```jsx <Positioner sideOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.height : anchor.width; }} /> ```
Defaults to 6.
alignOffsetnumber | OffsetFunction: Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side. @example ```jsx <Positioner alignOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.width : anchor.height; }} /> ```
Defaults to 0.
anchorElement | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null: An element to position the popup against. By default, the popup will be positioned against the trigger.
positionMethod"absolute" | "fixed": Determines which CSS `position` property to use.
Defaults to 'absolute'.
collisionBoundaryBoundary: An element or a rectangle that delimits the area that the popup is confined to.
Defaults to 'clipping-ancestors'.
collisionPaddingPadding: Additional space to maintain from the edge of the collision boundary.
Defaults to 5.
stickyboolean: Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
Defaults to false.
arrowPaddingnumber: Minimum distance to maintain between the arrow and the edges of the popup. Use it to prevent the arrow element from hanging out of the rounded corners of a popup.
Defaults to 5.
disableAnchorTrackingboolean: Whether to disable the popup from tracking any layout shift of its positioning anchor.
Defaults to false.
collisionAvoidanceCollisionAvoidance: Determines how to handle collisions when positioning the popup. `side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`): - `'flip'`: keep the requested side when it fits; otherwise try the opposite side (`top` and `bottom`, or `left` and `right`). - `'shift'`: never change side; keep the requested side and move the popup within the clipping boundary so it stays visible. - `'none'`: do not correct side-axis overflow. `align` controls overflow on the alignment axis (`start`/`center`/`end`): - `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows. - `'shift'`: keep side and requested alignment, then nudge the popup along the alignment axis to fit. - `'none'`: do not correct alignment-axis overflow. `fallbackAxisSide` controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: - `'start'`: allow perpendicular fallback and try the logical start side first (`top` before `bottom`, or `left` before `right` in LTR). - `'end'`: allow perpendicular fallback and try the logical end side first (`bottom` before `top`, or `right` before `left` in LTR). - `'none'`: do not fallback to the perpendicular axis. When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`. If `align` is omitted, it defaults to `'flip'`. @example ```jsx <Positioner collisionAvoidance={{ side: 'shift', align: 'shift', fallbackAxisSide: 'none', }} /> ```

Tooltip.Provider

Inherited from TooltipProviderProps

delaynumber: How long to wait before opening the tooltip on hover. Specified in milliseconds.
closeDelaynumber: How long to wait before closing a tooltip. Specified in milliseconds.
timeoutnumber: Another tooltip will open instantly if the previous tooltip is closed within this timeout. Specified in milliseconds.
Defaults to 400.

Tooltip.Trigger

classNamestring | ((state: TooltipTriggerState) => string): CSS class applied to the element, or a function that returns a class based on the component's state.

Inherited from TooltipTriggerProps

handleTooltipHandle<unknown>: A handle to associate the trigger with a tooltip.
payloadunknown: A payload to pass to the tooltip when it is opened.
delaynumber: How long to wait before opening the tooltip on hover. Specified in milliseconds.
Defaults to 600.
closeOnClickboolean: Whether the tooltip should close when this trigger is clicked.
Defaults to true.
closeDelaynumber: How long to wait before closing the tooltip. Specified in milliseconds.
Defaults to 0.
disabledboolean: If `true`, the tooltip will not open when interacting with this trigger. Note that this doesn't apply the `disabled` attribute to the trigger element. If you want to disable the trigger element itself, you can pass the `disabled` prop to the trigger element via the `render` prop.
Defaults to false.

Previous page← Toast Next pageAccordion →