Skip to content

fix(ui): Ensure tooltips render above dialog content#9093

Merged
alexcarpenter merged 1 commit into
mainfrom
carp/fix-tooltip-z-index
Jul 6, 2026
Merged

fix(ui): Ensure tooltips render above dialog content#9093
alexcarpenter merged 1 commit into
mainfrom
carp/fix-tooltip-z-index

Conversation

@alexcarpenter

@alexcarpenter alexcarpenter commented Jul 6, 2026

Copy link
Copy Markdown
Member

Description

Fix tooltips rendering behind modals (for example on the organization profile Security page). Tooltips now layer above modal content, and pressing Escape or clicking outside while a tooltip is open inside a modal closes only the tooltip instead of also dismissing the modal.

BEFORE

before.mov

AFTER

after.mov

Checklist

  • pnpm test runs as expected.
  • pnpm build runs as expected.
  • (If applicable) JSDoc comments have been added or updated for any package exports
  • (If applicable) Documentation has been updated

Type of change

  • 🐛 Bug fix
  • 🌟 New feature
  • 🔨 Breaking change
  • 📖 Refactoring / dependency upgrade / documentation
  • other:

Summary by CodeRabbit

  • New Features
    • Tooltips now appear above modal content, improving visibility in layered interfaces.
    • Tooltips inside a modal now close on Escape or outside click without closing the modal itself.
  • Bug Fixes
    • Improved tooltip stacking so they render at the correct priority across the UI.

@changeset-bot

changeset-bot Bot commented Jul 6, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: b5cd937

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

This PR includes changesets to release 3 packages
Name Type
@clerk/ui Patch
@clerk/chrome-extension Patch
@clerk/swingset 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

vercel Bot commented Jul 6, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
clerk-js-sandbox Ready Ready Preview, Comment Jul 6, 2026 4:02pm
swingset Ready Ready Preview, Comment Jul 6, 2026 4:02pm

Request Review

@coderabbitai

coderabbitai Bot commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

This PR fixes tooltip layering by adding floating-tree node awareness to the Tooltip component (useFloatingNodeId, FloatingNode, withFloatingTree) and introduces a dedicated tooltip z-index value above modal, with a changeset documenting the fix.

Changes

Tooltip layering fix

Layer / File(s) Summary
Tooltip nodeId contract and imports
packages/ui/src/elements/Tooltip.tsx
Adds useFloatingNodeId import and reorganizes local imports; UseTooltipReturn gains a nodeId: string | undefined field.
useTooltip nodeId wiring and FloatingTree integration
packages/ui/src/elements/Tooltip.tsx
useTooltip computes nodeId and passes it to useFloating, the return value, and memo deps; Tooltip.Root is wrapped with withFloatingTree; TooltipContent wraps its floating portal in FloatingNode.
Tooltip z-index and changeset
packages/ui/src/foundations/zIndices.ts, .changeset/tooltip-above-modal.md
Adds a tooltip: '12000' z-index entry and a changeset describing the fix and updated Escape/outside-click dismissal behavior.

Estimated code review effort: 2 (Simple) | ~12 minutes

Sequence Diagram(s)

sequenceDiagram
  participant TooltipRoot
  participant useTooltip
  participant FloatingTree
  participant TooltipContent
  TooltipRoot->>useTooltip: initialize with options
  useTooltip->>FloatingTree: useFloatingNodeId()
  FloatingTree-->>useTooltip: nodeId
  useTooltip-->>TooltipRoot: context with nodeId
  TooltipRoot->>TooltipContent: render with context
  TooltipContent->>FloatingTree: wrap portal in FloatingNode id
Loading

Poem

A tooltip hopped above the modal's crown,
No longer trapped, no longer held down.
With nodeId whispered through the tree so wide,
Escape now closes just the tip, not the ride. 🐰✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly matches the main change: fixing tooltips to render above dialog/modal content.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

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

@alexcarpenter alexcarpenter marked this pull request as ready for review July 6, 2026 16:02
@github-actions github-actions Bot added the ui label Jul 6, 2026
@pkg-pr-new

pkg-pr-new Bot commented Jul 6, 2026

Copy link
Copy Markdown

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9093

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9093

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9093

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9093

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9093

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9093

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9093

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9093

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9093

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9093

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9093

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9093

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9093

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9093

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9093

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9093

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9093

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9093

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9093

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9093

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9093

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9093

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9093

commit: b5cd937

@github-actions

github-actions Bot commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

API Changes Report

Generated by Break Check on 2026-07-06T16:06:00.121Z

Summary

Metric Count
Packages analyzed 19
Packages with changes 0
🔴 Breaking changes 0
🟡 Non-breaking changes 0
🟢 Additions 0

No API Changes Detected

All packages have stable APIs with no detected changes.


Report generated by Break Check

Last ran on b5cd937.

@coderabbitai coderabbitai Bot 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.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
packages/ui/src/elements/Tooltip.tsx (1)

77-105: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Add bubbles: false to useDismiss. With the nested FloatingTree setup, the default outsidePress dismissal can bubble to the parent modal and close it too. The Escape-key case doesn’t rely on bubbling here.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/ui/src/elements/Tooltip.tsx` around lines 77 - 105, Add bails-out
for nested tooltip dismissal by updating the useDismiss call in Tooltip to
disable bubbling for outside-press handling. The issue is that the current
dismiss behavior can propagate through the FloatingTree and close a parent modal
when a tooltip is dismissed; update the useDismiss configuration in Tooltip.tsx
so outside presses do not bubble. Keep the Escape-key behavior unchanged while
ensuring the tooltip still closes correctly on outside interaction.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@packages/ui/src/elements/Tooltip.tsx`:
- Around line 77-105: Add bails-out for nested tooltip dismissal by updating the
useDismiss call in Tooltip to disable bubbling for outside-press handling. The
issue is that the current dismiss behavior can propagate through the
FloatingTree and close a parent modal when a tooltip is dismissed; update the
useDismiss configuration in Tooltip.tsx so outside presses do not bubble. Keep
the Escape-key behavior unchanged while ensuring the tooltip still closes
correctly on outside interaction.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: a016d2e6-5655-4b8a-af45-6e7d69aae03c

📥 Commits

Reviewing files that changed from the base of the PR and between f2d9e4b and b5cd937.

📒 Files selected for processing (3)
  • .changeset/tooltip-above-modal.md
  • packages/ui/src/elements/Tooltip.tsx
  • packages/ui/src/foundations/zIndices.ts

@wobsoriano wobsoriano left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

makes sense!

@alexcarpenter alexcarpenter merged commit f9afa48 into main Jul 6, 2026
57 of 65 checks passed
@alexcarpenter alexcarpenter deleted the carp/fix-tooltip-z-index branch July 6, 2026 18:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants