Tooltip clipped by overflow/scroll ancestors instead of viewport.

[jrockwood]

Describe the bug

<Tooltip>'s default Floating UI boundary is its nearest scroll/overflow ancestor, not the viewport. Tooltips inside scrolling containers (tables, dialogs, sidebars, any element with overflow: auto/scroll/hidden) get visually clipped when they would otherwise extend past the container's edge — even when there is plenty of room in the viewport itself.

The fix on the consumer side is to manually pass positioning={{ boundary: () => document.body }} at every call site, but that's easy to forget and produces silent visual regressions when missed.

To Reproduce

1. Render any container with overflow: auto or overflow: hidden that's smaller than the tooltip would occupy when fully visible.
2. Place a <Tooltip> inside it whose trigger is near the container's edge.
3. Hover the trigger.

The tooltip is clipped at the container's edge instead of overflowing into the viewport.

Reproduction

import { Tooltip } from '@qualcomm-ui/react/tooltip'

export function TooltipClippingRepro() {
  return (
    <div style={{ width: 200, height: 80, overflow: 'auto', border: '1px solid #ccc', padding: 8 }}>
      <Tooltip trigger={<button type="button">Hover me</button>}>
        This tooltip's content gets clipped at the edge of the surrounding scroll container, even
        though the viewport has plenty of space.
      </Tooltip>
    </div>
  )
}

Compare with the same <Tooltip> rendered with the workaround:

<Tooltip
  positioning={{ boundary: () => document.body }}
  trigger={<button type="button">Hover me</button>}
>
  …
</Tooltip>

The workaround version renders correctly — proof the fix is just a default change.

Expected behavior

The tooltip should be bounded by the viewport by default, not by the nearest scrolling ancestor. This matches how Tooltips work in MUI, Radix, Mantine, Chakra, and Floating UI's own examples — and matches what the component is conceptually for (an overlay that escapes its container).

If clip-to-ancestor is a desired alternative for some cases, expose it as a prop rather than the default.

Environment

• OS: macOS 15
• Browser: Chrome 132
• Version: @qualcomm-ui/react@1.22.0, @qualcomm-ui/qds-core@1.28.0

[R-Bower]

Justin Rockwood (@jrockwood) I'm having trouble reproducing this. I tested for this specifically when I built the component. It's one of the reasons why we went with floating-ui in our legacy lib many years ago. I wonder if there's other CSS causing this on your side. Can you double check?

<div className="flex h-[calc(100vh-64px)] w-full items-center justify-center">
  <div
    style={{
      border: "1px solid #ccc",
      height: 80,
      // I also tried 'scroll' here, but the result is the same either way
      overflow: "auto",
      padding: 8,
      width: 200,
    }}
  >
    <Tooltip trigger={<button type="button">Hover me</button>}>
      This tooltip's content gets clipped at the edge of the surrounding
      scroll container, even though the viewport has plenty of space.
    </Tooltip>
  </div>
</div>

[jrockwood]

Ryan Bower (@R-Bower) thanks for taking a look — you're right that the boundary clipping doesn't reproduce. Sorry about the misdirection: I conflated two symptoms in the original report. The boundary fix in our wrapper had been there since the component first landed, but when I re-tested today after removing it, no clipping occurred. So the real bug is not boundary clipping — it's a broken z-index, which I think the original symptoms got blamed on the wrong cause. Re-stating the actual issue cleanly:

Restated bug — tooltip positioner has no working z-index

The tooltip positioner has two problematic inline styles applied at the same time:

z-index: var(--z-index);
--z-index: auto;

Both are inline. So z-index: var(--z-index) resolves to auto, and the positioner ends up below anything in the page that has a positive z-index. In our case it loses to a sticky table header at z-index: 10 and is visually painted underneath the header band.

The --z-index variable is set to a real value (calc(var(--z-index-tooltip) + var(--layer-index, 0))) — but on .qui-tooltip__content, which is a child of the positioner, not the positioner itself. So the variable cascade never reaches the element that actually needs it.

Reproduction

import { Tooltip } from '@qualcomm-ui/react/tooltip'

export function TooltipZIndexRepro() {
  return (
    <div className="flex h-[calc(100vh-64px)] w-full flex-col">
      {/* A sticky element with any positive z-index — common pattern for sticky table headers,
          fixed top bars, etc. */}
      <div className="sticky top-0 z-10 bg-background-neutral-10 p-4 shadow">
        Sticky bar (z-index: 10)
      </div>

      {/* Spacer to push the tooltip target near the sticky bar. */}
      <div className="h-[600px]" />

      <div className="p-4">
        <Tooltip trigger={<button type="button">Hover me</button>}>
          This tooltip's positioner has `z-index: auto`, so when its computed position would overlap
          the sticky bar above (z-index: 10), it renders behind the sticky bar instead of above it.
        </Tooltip>
      </div>
    </div>
  )
}

To verify in DevTools while hovering the trigger:

const positioner = document.querySelector('[data-tooltip-part="positioner"]')
getComputedStyle(positioner).zIndex            // → "auto"
positioner.getAttribute('style')               // contains both "z-index: var(--z-index)" and "--z-index: auto"
getComputedStyle(positioner).getPropertyValue('--z-index')  // → "auto"

Suggested fix

Either:

1. Stop emitting --z-index: auto on the positioner (so the cascade can pick up a real value defined elsewhere), or
2. Define --z-index on the positioner itself (the same way .qui-tooltip__content does) so QUI's existing z-index: var(--z-index) resolves to the tooltip layer.

Workaround consumers are forced to use

<Tooltip
  positionerProps={{ className: '[--z-index:var(--q-zindex-tooltip)]!' }}
  trigger={...}
>...</Tooltip>

The !important is needed because the --z-index: auto is set inline.

Sorry for the misdirection

The original "boundary clipping" framing was wrong — Floating UI does the right thing there, just as you found. I'd suggest renaming this issue to "Tooltip positioner has no working z-index" or similar. Happy to file a fresh issue if that's easier than re-titling this one.