Skip to content

fix(tooltip): prevent tooltip from staying visible when clicking triggers that open overlays #5914

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
driuqzy wants to merge 5 commits into
base: v3
Choose a base branch
from
Open

fix(tooltip): prevent tooltip from staying visible when clicking triggers that open overlays #5914

driuqzy wants to merge 5 commits into from
+106 −4

Conversation

@driuqzy
Copy link

@driuqzy driuqzy commented Nov 19, 2025

Description

Fixes #5912

This PR resolves an issue where tooltips remain visible when clicking a button that opens other overlays (popovers, menus, dialogs, etc.).

The Problem

When a user:

  1. Hovers over a button with a tooltip (tooltip shows)
  2. Clicks the button to open a popover
  3. The tooltip stays visible, overlapping the popover content

This happens because React Aria attempts to reopen the tooltip immediately after it closes (since the mouse is still hovering), creating a race condition.

The Solution

Implements a "force-hide" mechanism that:

  • Closes the tooltip when clicked
  • Prevents immediate reopening for 500ms
  • Allows normal tooltip behavior after the delay

The fix uses React Aria's official controlled state API (isOpen/onOpenChange) and is completely generic—it works with all overlays (popovers, menus, dialogs) and any click action.

Changes

  • tooltip.tsx: Added controlled state management with force-hide logic
  • tooltip.stories.tsx: Added WithPopover story demonstrating the fix

Testing

Test in Storybook:

  1. Navigate to Components/Overlays/Tooltip → WithPopover
  2. Hover over the Settings button (tooltip appears)
  3. Click the button (popover opens, tooltip closes immediately)
  4. ✅ Tooltip should not overlap the popover

Notes

  • No breaking changes—backward compatible with all existing usage
  • Works universally with any overlay component
  • 500ms delay is long enough to prevent race condition but short enough to not impact UX

driuqzy and others added 4 commits November 18, 2025 23:17
@driuqzy @claude
fix(tooltip): close tooltip on click to prevent conflict with popover
62a4e4c 
This fix resolves issue heroui-inc#5912 for v3 where the tooltip would stay open
when clicking a button that also triggers a popover.

Changes:
- Added onClick handler to TooltipRoot (TooltipTriggerPrimitive wrapper)
- Handler dispatches a mouseleave event to trigger React Aria's close logic
- Works with both direct children (Button) and Tooltip.Trigger patterns
- Maintains backward compatibility with all existing v3 tooltip usage

The fix intercepts clicks at the root level, ensuring tooltips close
regardless of how the trigger element is structured, preventing visual
overlap when popovers or other overlays open.

Closes heroui-inc#5912

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
@driuqzy
test(tooltip): add story to test tooltip+popover interaction
cefaee6
@driuqzy @claude
fix(tooltip): prevent tooltip from staying visible when clicking butt…
5047b63 
…ons with popovers

Fixes heroui-inc#5912

When a button with a tooltip is clicked to open a popover or dialog, the tooltip
now properly closes and stays closed instead of remaining visible over the overlay.

The fix works by:
1. Using controlled `isOpen` state on TooltipTrigger to manage tooltip visibility
2. When tooltip closes (via onOpenChange), setting a `forceHide` flag in context
3. TooltipContent component checks `forceHide` and returns null to prevent rendering
4. After 500ms, clearing `forceHide` to restore normal tooltip behavior

This approach ensures the tooltip doesn't interfere with popover/dialog interactions
while maintaining normal hover behavior for subsequent interactions.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
@driuqzy @claude
refactor(tooltip): improve comments and simplify story
9817b0b 
- Clarify comment to mention overlays (not just popovers) for accuracy
- Add detailed explanation of 500ms timeout rationale
- Simplify WithPopover story to be more user-friendly and less verbose
- Remove test-specific language from story, make it a useful example

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
@driuqzy driuqzy requested a review from jrgarciadev as a code owner November 19, 2025 09:44
@changeset-bot
Copy link

changeset-bot bot commented Nov 19, 2025 •
edited
Loading

🦋 Changeset detected

Latest commit: ac144b8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@heroui/react Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@vercel
Copy link

vercel bot commented Nov 19, 2025

@driuqzy is attempting to deploy a commit to the HeroUI Inc Team on Vercel.

A member of the Team first needs to authorize it.

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Nov 19, 2025

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

  • Provide your own instructions using the high_level_summary_instructions setting.
  • Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
  • Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

  1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
  2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
  3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
  4. 📊 Contributor Summary — Include a Markdown table showing contributions:
    | Contributor | Lines Added | Lines Removed | Files Changed |
  5. ✔️ Additional Notes — Add any extra reviewer context.
    Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@driuqzy @claude
chore: add changeset for tooltip fix
ac144b8 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jrgarciadev jrgarciadev Awaiting requested review from jrgarciadev jrgarciadev is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@driuqzy