Tooltips
Plain and rich Material tooltips with distinct non-interactive tooltip and actionable non-modal dialog semantics.
Tooltips provide contextual supporting information anchored to another control. Plain and rich Material tooltips share a visual family, but actionable rich content requires a different browser semantic model.
When to use
Use a plain tooltip for short, supplemental text that clarifies an unfamiliar icon or control. Do not hide essential instructions only in hover content. Use a rich tooltip when the supporting content genuinely needs a title or action and should remain available long enough to interact with.
Plain tooltip
TooltipTrigger + PlainTooltip follows the non-interactive tooltip pattern: trigger relationship, hover/focus timing, placement, portal behavior, and accessible description wiring are owned by React Aria.
<TooltipTrigger>
<Button>Info</Button>
<PlainTooltip>Short supporting context</PlainTooltip>
</TooltipTrigger>Keep plain tooltip content non-interactive. If users must move focus into the overlay, it is no longer a plain tooltip interaction.
Rich tooltip
RichTooltip may contain an action, so exposing it as ARIA tooltip would be incorrect. It is built on React Aria PreviewTrigger + Popover: React Aria owns hover/focus timing, long press, safe-area pointer travel, Tab focus travel, popup relationships, Escape behavior, and non-modal dialog semantics.
<RichTooltipTrigger>
<Button>Shortcuts</Button>
<RichTooltip
title="Keyboard shortcuts"
action={(close) => <TextButton onPress={close}>Got it</TextButton>}
>
Press Command K to open search.
</RichTooltip>
</RichTooltipTrigger>Focus may move into the rich action without modal focus containment. Escape returns focus to the trigger and touch users can open the preview with a long press. isPersistent defaults to true for Material rich tooltips. React Aria does not expose an equivalent persistent-preview option, and PreviewTrigger intentionally uses a non-dismissable non-modal Popover, so m3-ui retains a small close-filter adapter plus React Aria useInteractOutside for Material's outside-dismiss behavior. No document-level pointer listener is implemented by m3-ui.
Caret
Both PlainTooltip and RichTooltip accept an opt-in caret prop. It is off by default, matching the reviewed Compose API where the caret shape is nullable.
<TooltipTrigger>
<Button>Info</Button>
<PlainTooltip caret placement="top">
Supporting context
</PlainTooltip>
</TooltipTrigger>The default Material caret is 16×8 px and inherits the tooltip container color. It is rendered through React Aria OverlayArrow, so React Aria owns arrow coordinates, collision flips, and resolved placement while Material supplies only triangle geometry and paint. Logical start/end placement follows React Aria locale direction; the explicit per-component dir override is adapted for compatibility because RAC positioning reads locale direction rather than the local DOM attribute.
Portals and theme context
Tooltip surfaces are portalled. Public theme variables are projected into the portal so nested Material themes remain visually coherent without leaking component-private implementation variables.
Accessibility
Ensure the trigger is reachable without hover and that plain tooltip text remains concise. Do not place links/buttons inside PlainTooltip.
For rich tooltips, provide enough title/content to identify the non-modal dialog-like surface and keep actions keyboard reachable. Avoid treating an actionable overlay as role="tooltip", which does not support interactive descendants as a user interaction model.
API reference
PlainTooltip
PlainTooltip({ caret, children, containerColor, contentColor, shape, maxWidth, placement, dir, offset, className, style, UNSTABLE_portalContainer, ...props }: PlainTooltipProps): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
caret | boolean | undefined | false | Render the default Material 3 caret using React Aria OverlayArrow. | @m3-ui/ui |
containerColor | Property.BackgroundColor | undefined | — | — | @m3-ui/ui |
contentColor | Property.Color | undefined | — | — | @m3-ui/ui |
maxWidth | Property.MaxWidth<string | number> | undefined | — | — | @m3-ui/ui |
shape | Property.BorderRadius<string | number> | undefined | — | — | @m3-ui/ui |
Inherited React / web props (90)
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
aria-describedby | string | undefined | — | Identifies the element (or elements) that describes the object. | @react-types/shared |
aria-details | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. | @react-types/shared |
aria-label | string | undefined | — | Defines a string value that labels the current element. | @react-types/shared |
aria-labelledby | string | undefined | — | Identifies the element (or elements) that labels the current element. | @react-types/shared |
arrowBoundaryOffset | number | undefined | 0 | The minimum distance the arrow's edge should be from the edge of the overlay element. | react-aria |
children | ChildrenOrFunction<TooltipRenderProps> | — | The children of the component. A function may be provided to alter the children based on component state. | react-aria-components |
className | ClassNameOrFunction<TooltipRenderProps> | undefined | 'react-aria-Tooltip' | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. | react-aria-components |
containerPadding | number | undefined | 12 | The placement padding that should be applied between the element and its surrounding container. | react-aria |
crossOffset | number | undefined | 0 | The additional offset applied along the cross axis between the element and its anchor element. | react-aria |
defaultOpen | boolean | undefined | — | Whether the overlay is open by default (uncontrolled). | react-stately |
dir | string | undefined | — | — | @react-types/shared |
hidden | boolean | undefined | — | — | @react-types/shared |
inert | boolean | undefined | — | — | @react-types/shared |
isEntering | boolean | undefined | — | Whether the tooltip is currently performing an entry animation. | react-aria-components |
isExiting | boolean | undefined | — | Whether the tooltip is currently performing an exit animation. | react-aria-components |
isOpen | boolean | undefined | — | Whether the element is rendered. | react-aria |
lang | string | undefined | — | — | @react-types/shared |
offset | number | undefined | plainTooltipRuntime.spacingBetweenTooltipAndAnchor | The additional offset applied along the main axis between the element and its anchor element. | react-aria |
onAnimationEnd | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationEndCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIteration | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIterationCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStart | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStartCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenu | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenuCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onGotPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onGotPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDown | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDownCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseEnter | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseLeave | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMove | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMoveCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOut | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOutCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOver | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOverCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUp | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUpCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onOpenChange | ((isOpen: boolean) => void) | undefined | — | Handler that is called when the overlay's open state changes. | react-stately |
onPointerCancel | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancelCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDown | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDownCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerEnter | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerLeave | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMove | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMoveCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOut | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOutCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOver | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOverCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUp | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUpCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScroll | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScrollCapture | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancel | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancelCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEnd | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEndCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMove | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMoveCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStart | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStartCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancel | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancelCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEnd | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEndCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRun | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRunCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStart | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStartCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheel | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheelCapture | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
placement | Placement | undefined | 'top' | The placement of the tooltip with respect to the trigger. | react-aria-components |
render | DOMRenderFunction<"div", TooltipRenderProps> | undefined | — | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. | react-aria-components |
shouldFlip | boolean | undefined | true | Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely. | react-aria |
style | StyleOrFunction<TooltipRenderProps> | undefined | — | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. | react-aria-components |
translate | "yes" | "no" | undefined | — | — | @react-types/shared |
triggerRef | RefObject<Element | null> | undefined | — | The ref for the element which the tooltip positions itself with respect to. When used within a TooltipTrigger this is set automatically. It is only required when used standalone. | react-aria-components |
UNSTABLE_portalContainer | Element | undefined | document.body | The container element in which the overlay portal will be placed. This may have unknown behavior depending on where it is portalled to. | react-aria-components |
Source: packages/ui/src/components/Tooltip/Tooltip.tsx:123
Material fidelity and web adaptation
- Family
- Tooltips
- Provenance
- spec: Material 3 overview · web: Browser and React Aria semantics · adaptation: m3-ui web adaptation
- Compose mapping
- PlainTooltip · RichTooltip · TooltipDefaults.caretSize/caretShape · TooltipBox/tooltip state behavior
- Visual fidelity
- aligned: Reviewed plain/rich tooltip surfaces and the canonical 16×8 optional caret are covered across placement, theme, and collision-flip presentation.
- Behavior fidelity
- adapted: Plain tooltips use the React Aria tooltip pattern and accessible description wiring. Rich tooltips can contain actions, so they intentionally use non-modal dialog semantics with aria-haspopup/expanded/controls relationships instead of misusing the non-interactive ARIA tooltip role. Logical start/end caret placement is normalized to physical placement from explicit dir or React Aria locale direction, while React Aria still owns measurement, collision, and flipping.
- Semantics fidelity
- adapted: Plain tooltips use the React Aria tooltip pattern and accessible description wiring. Rich tooltips can contain actions, so they intentionally use non-modal dialog semantics with aria-haspopup/expanded/controls relationships instead of misusing the non-interactive ARIA tooltip role. Logical start/end caret placement is normalized to physical placement from explicit dir or React Aria locale direction, while React Aria still owns measurement, collision, and flipping.
- Adaptations
- Plain tooltips use the React Aria tooltip pattern and accessible description wiring. Rich tooltips can contain actions, so they intentionally use non-modal dialog semantics with aria-haspopup/expanded/controls relationships instead of misusing the non-interactive ARIA tooltip role. Logical start/end caret placement is normalized to physical placement from explicit dir or React Aria locale direction, while React Aria still owns measurement, collision, and flipping.
Material supplies tooltip hierarchy, shape, typography, color, and plain/rich presentation. React Aria's plain tooltip semantics and the explicit non-modal dialog-style mapping for actionable rich content are browser accessibility adaptations.
Related components
- Menus — temporary action/choice collections.
- Dialog — modal focused content.
- Icon button — common trigger that may need supplemental labeling/context.