Skip to content

feat(tooltip)!: modernize Tooltip to Material Design 3 - #4994

Open
burczu wants to merge 81 commits into
callstack:mainfrom
burczu:feat/tooltip-md3-modernization
Open

burczu wants to merge 81 commits into
callstack:mainfrom
burczu:feat/tooltip-md3-modernization

Conversation

@burczu

@burczu burczu commented Jun 10, 2026 •

Copy link
Copy Markdown

Motivation

Tooltip didn't follow MD3: wrong colors and type, no animation, no rich variant.

  • Plain: inverseSurface, bodySmall, fade.
  • New Tooltip.Rich: title, content, actions, onDismiss. A tap toggles it; on web hover or focus opens it, Escape closes it.
  • Keyboard and screen reader support.

Breaking: children is a render function; spread its props onto the trigger.

Related issue

Closes #4980, closes #4074, closes #5003.

Screenshots / Videos

tooltip_ios.mp4
tooltip_android.mp4
tooltip_web.mp4

Test plan

Example app, Tooltips:

  • Native: long-press an icon; tap +, then outside or the info icon (switches in one tap). Back still navigates.
  • Web: hover into the card; Tab to +, ArrowDown, Escape.
  • RTL, VoiceOver, TalkBack.

@burczu
burczu force-pushed the feat/tooltip-md3-modernization branch from cc19756 to bdcf0e5 Compare June 11, 2026 07:34
@burczu
burczu requested a review from satya164 June 16, 2026 08:07
Comment thread src/components/Tooltip/tokens.ts Resolved
Comment thread src/components/Tooltip/RichTooltip.tsx Resolved
Comment thread src/components/Tooltip/RichTooltip.tsx Resolved
Comment thread src/components/Tooltip/tokens.ts Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR modernizes the Tooltip component to align with the Material Design 3 tooltip spec, adds the missing “rich” tooltip variant, and introduces an MD3 motion-token-driven fade in/out transition shared by both variants.

Changes:

  • Updated plain tooltip styling to MD3 roles/typescale and replaced instantaneous show/hide with a fade transition.
  • Added Tooltip.Rich (compound component) supporting optional title, rich content, and actions, with web hover behavior.
  • Extracted shared constants and behavior into Tooltip/tokens.ts and useTooltipFade.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
src/index.tsx Re-exports Tooltip from the new components/Tooltip entry and exposes TooltipRichProps.
src/components/Tooltip/Tooltip.tsx Plain tooltip updated to MD3 tokens + shared fade lifecycle via useTooltipFade.
src/components/Tooltip/tokens.ts Adds MD3 color/shape/typescale/motion token definitions for plain + rich tooltips.
src/components/Tooltip/RichTooltip.tsx Implements the new rich tooltip variant, including backdrop dismissal and web hover behavior.
src/components/Tooltip/index.tsx Creates the compound component export (Tooltip.Rich).
src/components/Tooltip/hooks.ts Adds useTooltipFade to keep tooltips mounted through exit fade and avoid “flash at wrong position”.
src/components/tests/Tooltip.test.tsx Extends tests for MD3 styling, fade lifecycle, and Tooltip.Rich behaviors.
example/src/Examples/TooltipExample.tsx Adds a “Rich tooltips” example section demonstrating title/content/actions variants.
docs/docusaurus.config.js Registers TooltipRich for docs component mapping.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread src/components/Tooltip/RichTooltip.tsx Resolved
Comment thread src/components/Tooltip/RichTooltip.tsx Resolved
Comment thread src/components/Tooltip/RichTooltip.tsx Resolved
burczu added a commit to burczu/react-native-paper that referenced this pull request Jun 17, 2026
Remove the `satisfies` blocks duplicating the token object shapes (the color
roles are already type-checked at the usage sites) and the unused `action`
color token.

Re callstack#4994
burczu added a commit to burczu/react-native-paper that referenced this pull request Jun 17, 2026
Replace React.cloneElement and children.props reading with a render-prop
trigger and a render-prop `actions` that receives a `dismiss` callback. This
is type-safe and composable, lets the consumer own the trigger element (so
disabled state isn't forced), wires web hover + keyboard focus, and removes the
onTouchEnd-based action dismissal that didn't fire for click/keyboard.

Re callstack#4994
burczu added a commit to burczu/react-native-paper that referenced this pull request Jun 17, 2026
Give the full-screen backdrop an accessibilityLabel and hint so screen reader
users understand it dismisses the tooltip.

Re callstack#4994
@burczu
burczu requested a review from satya164 June 17, 2026 17:04

@satya164 satya164 left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the tooltip is broken on web

  • it keeps switching between hovered/unhovered
  • it doesn't react to clicking on the button, so it's inaccessible if you're using a touchscreen.
  • if the whole page is scrolled (the example seems to have a bug that makes it scrollable beyond the cpntent height - though it'd likely happen for normal whole page scroll as well), the tooltip is positioned wrongly
tooltip-web.mp4

the animation is broken on android with elevation:

tooltip-android.mp4

the tooltip should also not be attached to the edge. there needs to be some spacing.

there can be multiple tooltips shown at the same time:

multiple-tooltips.mp4

the FAB doesn't show tooltips

also please apply safe area insets to the the scrollable view.

Comment thread src/components/Tooltip/hooks.ts Resolved
Comment thread src/components/Tooltip/hooks.ts Resolved
Comment thread src/components/Tooltip/hooks.ts Resolved
Comment thread src/components/Tooltip/RichTooltip.tsx Resolved
Comment thread src/components/Tooltip/RichTooltip.tsx Resolved
Comment thread src/components/Tooltip/RichTooltip.tsx Resolved
Comment thread src/components/Tooltip/RichTooltip.tsx Resolved
Comment thread src/components/Tooltip/RichTooltip.tsx Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Comment thread docs/docusaurus.config.js Resolved
Comment thread src/components/Tooltip/RichTooltip.tsx Resolved
burczu and others added 13 commits June 30, 2026 14:16
Container now uses inverseSurface and text uses inverseOnSurface per the
MD3 tooltip spec (previously onSurface/surface). Text variant changes from
labelLarge to bodySmall (12sp). Tokens are extracted into a new tokens.ts
following the FAB pattern; the rich and motion token sets land here too and
are consumed in later commits.
The plain tooltip now fades in on show and out on hide using Reanimated,
per the MD3 motion spec (enter short3/standardDecelerate, exit
short2/standardAccelerate). Show/hide intent (visible) is split from mount
state (rendered) so the tooltip stays mounted through the exit fade before
unmounting. Honors reduce-motion via useReduceMotion.
Adds Tooltip.Rich, a persistent, interactive rich tooltip per the MD3 spec:
an optional subhead title, supporting body text (string or element) and a
row of action buttons on a surfaceContainer surface at elevation level 2
with a 12dp corner.

Exposed as a compound component (Object.assign) so the plain Tooltip stays
untouched. Uncontrolled tap-to-toggle: tapping the trigger toggles it,
tapping the Portal backdrop or selecting an action dismisses it. On web it
opens on hover and bridges the trigger-to-tooltip gap before hiding. Reuses
the plain tooltip's Reanimated fade and reduce-motion handling.
Adds a 'Rich tooltips' section to the example app (full title/content/actions
variant plus a body-only one), registers the RichTooltip page in the docs
component map so the generated docs cover Tooltip.Rich, and cross-references
the rich variant from the plain Tooltip JSDoc.
The fade lifecycle (mount-through-exit, opacity, measurement, motion
configs, reduce-motion) was duplicated between Tooltip and Tooltip.Rich.
Extract it into a useTooltipFade hook so both variants share one
implementation. No behavior change.
Remove the `satisfies` blocks duplicating the token object shapes (the color
roles are already type-checked at the usage sites) and the unused `action`
color token.

Re callstack#4994
Replace React.cloneElement and children.props reading with a render-prop
trigger and a render-prop `actions` that receives a `dismiss` callback. This
is type-safe and composable, lets the consumer own the trigger element (so
disabled state isn't forced), wires web hover + keyboard focus, and removes the
onTouchEnd-based action dismissal that didn't fire for click/keyboard.

Re callstack#4994
Give the full-screen backdrop an accessibilityLabel and hint so screen reader
users understand it dismisses the tooltip.

Re callstack#4994
The render-prop handed hover/focus handlers to the trigger element, but
triggers like IconButton don't forward onHoverIn/onHoverOut on web, so
rich tooltips never opened on hover. Carry the handlers on the wrapper
(web only) like the plain Tooltip does; keep press on the trigger for
mobile so it doesn't double-fire. Add a regression test with a
non-forwarding trigger.
Replace the visible->setRendered(true) effect with a render-time guard
(if (visible && !rendered) setRendered(true)), so the mounted state is
derived during render instead of synced from an effect.

Addresses review feedback on useTooltipFade.
@lukewalczak

Copy link
Copy Markdown
Member

/review

@lukewalczak lukewalczak removed the wip label Nov 18, 2026
@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 2 new findings on db06c3c. The verdict and the full list are in the summary comment.

Comment thread src/components/Tooltip/registry.ts Resolved
Comment thread src/components/Tooltip/RichTooltip.tsx Resolved
@lukewalczak

Copy link
Copy Markdown
Member

/review

@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of bb2bcfe

Since the review of db06c3c: 0 new · 0 still open · 2 no longer raised (1 marked fixed)

No open findings.

2 findings below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (677ab9f2b2cf).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

Comment thread src/components/Tooltip/Tooltip.tsx Resolved
Comment thread src/components/Tooltip/Tooltip.tsx Resolved
Comment thread src/components/Tooltip/Tooltip.tsx Resolved
Comment thread src/components/Tooltip/tokens.ts Resolved
Comment thread example/src/Examples/TooltipExample.tsx Resolved
Comment thread src/components/Tooltip/registry.ts Resolved
- close the plain tooltip on Escape on web
- release the singleton slot when a tooltip hides or unmounts
- forward onFocus, onBlur and aria-describedby through FAB
- update the Tooltip colours in the docs and add Tooltip.Rich
- pass the Tooltip trigger as a render function in the Appbar tests
- pass the title as accessibilityHint on iOS and Android instead of
  aria-label, so a trigger keeps its own name
- add titleAsAriaLabel to use the title as the trigger's aria-label on
  every platform, for icon-only triggers
…rnization

# Conflicts:
#	example/src/Examples/TooltipExample.tsx
#	src/components/Tooltip/Tooltip.tsx

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

8 participants