feat: Add PopoverNext component built on Floating UI #7573

ggdouglas · 2025-09-18T01:27:37Z

Summary

Introduce PopoverNext as a modern, Floating UI–based replacement for Popover. The goal is near drop-in API compatibility to ease adoption, while migrating from Popper "modifiers" to Floating UI "middleware". This change also helps to unblock React 19 support as part of #7115.

Why: Popper v2 via react-popper isn’t actively maintained, and the ecosystem has moved to Floating UI. React 19 support is blocked by the legacy stack.
What: New PopoverNext component, docs, tests, and examples. Existing Popover component marked deprecated.
How:
- Ported the existing Popover from a class-based to a functional component, preserving existing behavior where possible.
- Maintained feature parity while switching the positioning engine to Floating UI.
- Exposed middleware as options instead of modifiers in new PopoverNext API.

Migration

Prop compatibility
- Preserved where feasible: children, renderTarget, content, isOpen/defaultIsOpen, onInteraction, onClose, usePortal, hasBackdrop, interactionKind, minimal, matchTargetWidth, etc.
Auto behavior
- The "auto" placement options are not supported in PopoverNext.
- Instead, for automatic placement behavior, omit placement entirely. When placement is undefined, PopoverNext uses Floating UI's automatic placement by default (via autoPlacement). See the docs: Floating UI autoPlacement.
Defaults and behavior notes
- Boundary defaults differ:
  - Popover: boundary="clippingParents"
  - PopoverNext: boundary="clippingAncestors"
  - To match legacy behavior precisely, set boundary="clippingParents" on PopoverNext.
- Dismiss and accessibility are preserved:
  - Classes.POPOVER_DISMISS, Classes.POPOVER_DISMISS_OVERRIDE, captureDismiss
  - aria-haspopup/aria-expanded, backdrop + focus behavior via Overlay2
Modifiers → Middleware mapping
- flip → flip
- preventOverflow → shift (use boundary/rootBoundary)
- offset → offset (mainAxis, crossAxis)
- arrow → arrow
Practical migration steps
- Switch imports to PopoverNext.
- Use the same props; modify placement, boundary, etc. where needed
- Translate any Popper modifiers to Floating UI middleware (migration utilities forthcoming)

Follow-ups

Migrate internal usages (Tooltip, menus, selects) to PopoverNext.
Provide codemods and a migration wiki page as adoption ramps.
Remove legacy Popover in a future major version

References

Origin issue: Add support for React 19 #7115
Deprecation of React-Popper #7139
Popper v2: docs, react-popper
Floating UI: site, migration guide

svc-palantir-github · 2025-09-18T01:35:37Z

Write docs for PopoverNext and add examples

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-09-18T02:06:17Z

Write docs for PopoverNext and add examples

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-09-18T17:24:36Z

Write docs for PopoverNext and add examples

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-09-19T20:28:40Z

Write docs for PopoverNext and add examples

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

packages/core/src/components/popover-next/popoverTarget.tsx

packages/core/src/components/popover-next/popover-next.md

invliD · 2025-09-24T20:17:34Z

packages/core/src/components/popover-next/popover-next.md

+@### Middleware
+
+Middleware allow us to customize Floating UI's positioning behavior. **PopoverNext** configures several of Floating UI's built-in middleware to handle things such as flipping, preventing overflow from a boundary element, and positioning the arrow.
+
+You may override the default middleware with the `middleware` prop, which is an object with key-value pairs representing the middleware name and its options object, respectively. See the [Floating UI middleware docs page](https://floating-ui.com/docs/middleware) for more info.
+
+<div class="@ns-callout @ns-intent-warning @ns-icon-warning-sign @ns-callout-has-body-content">
+    <h5 class="@ns-heading">Auto placement requires autoPlacement or flip middleware</h5>
+
+Be careful when disabling the "autoPlacement" or "flip" middleware, since automatic placement relies on them. If you _do_ decide to disable these middleware, be sure to also specify a placement which is specific (not automatic).


Do we need to support this API? It might be best to keep the simplest possible API for now until we know we need more, and even then maybe make it more semantic than just exposing all of Floating UI's API. That way, if we ever have to switch underlying libraries again, we might be able to get away without an API break next time.

I get the concern about keeping the API simple and future-proof, but I'm thinking we should probably keep the middleware prop for now.

The main thing is that we're going to need this flexibility pretty much immediately. Looking at the current codebase, submenus and tooltips already rely on custom modifiers for things like offset, flip, and preventOverflow.

blueprint/packages/core/src/components/menu/menuItem.tsx

Lines 308 to 314 in 031a998

const SUBMENU_POPOVER_MODIFIERS: PopoverProps["modifiers"] = {

// 20px padding - scrollbar width + a bit

flip: { enabled: true, options: { padding: 20, rootBoundary: "viewport" } },

// shift popover up 5px so MenuItems align

offset: { enabled: true, options: { offset: [-5, 0] } },

preventOverflow: { enabled: true, options: { padding: 20, rootBoundary: "viewport" } },

};

blueprint/packages/core/src/components/tooltip/tooltip.tsx

Lines 126 to 135 in 031a998

modifiers={{

arrow: {

enabled: !this.props.minimal,

},

offset: {

options: {

offset: [0, TOOLTIP_ARROW_SVG_SIZE / 2],

},

},

}}

Without exposing middleware, we'd either have to recreate all these specific APIs (which feels like more work for less flexibility) or continually add on to functionality during the migration.

I also think the middleware concept is actually pretty well-designed already. Floating UI's API is well-documented, and it's tough to anticipate all the positioning edge cases we might need to handle. A more semantic API would probably just end up being a thin wrapper around middleware anyway, and then we'd be maintaining our own abstraction layer.

On the future-proofing front, if we do need to switch libraries again someday, the middleware concept seems pretty universal. Popper had modifiers, Floating UI has middleware, so there's probably a pattern here. We could potentially create a compatibility layer that maps between different systems if needed.

What's your take? Are there specific middleware use cases that concern you, or do you have a suggestion on a clean wrapper we could use here?

invliD · 2025-09-24T20:18:27Z

packages/core/src/components/popover-next/popover-next.md

+@### Minimal style
+
+You can create a minimal popover by setting `minimal={true}`.
+This removes the arrow from the popover and makes the transitions more subtle.


I believe we've talked about this one before, but do we want to split these two into separate props now that we're redoing the API anyway?

Yeah, there are a few things to split out here:

Presence of the arrow

Offset of the popup element from the target

Animation style

I've split minimal into two separate props, arrow and animation. The arrow prop controls the display of the arrow and applies the correct amount of offset to accommodate the arrow. The animation prop solely controls the style of the animation ("scale" vs. "minimal"). 86cd4c0

packages/core/src/components/popover-next/popoverNextProps.ts

invliD · 2025-09-24T20:22:12Z

packages/core/src/components/popover-next/popoverPopup.tsx

+}
+
+function cssPropertyToString(value: string | number | undefined): string {
+    return value != null && !isNaN(Number(value)) ? `${value}px` : "";


What happens if you set left: (the empty string case)? Should we set the property at all in that case?

svc-palantir-github · 2025-09-25T02:08:39Z

[CR] Edit comments/markdown

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-09-25T02:32:20Z

[CR] Remove redundant `interactionKind` default in `PopoverTarget`

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-09-25T18:49:58Z

[CR] Redeclare new Placement type within Blueprint

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

mm-wang

Reviewed for syntax and understanding, mostly tried to get context and an example of how we structure these components. I'd love to hear more about how I can use and test this.

packages/core/src/components/popover-next/floatingUtils.ts

mm-wang · 2025-09-25T00:03:48Z

packages/core/src/components/popover-next/popoverNext.tsx

+
+export const PopoverNext = forwardRef<PopoverNextRef, PopoverNextProps>((props, ref) => {
+    const {
+        boundary = "clippingAncestors",


note: Thought it was odd that Floating UI didn't have an enum for this, but it looks like it's literally the string: https://floating-ui.com/docs/detectoverflow#boundary.

packages/core/src/components/popover-next/popoverNext.tsx

packages/core/src/components/popover-next/popoverNextProps.ts

packages/core/src/components/popover-next/popoverTarget.tsx

mm-wang · 2025-09-25T19:32:33Z

packages/core/src/components/popover-next/popoverPopup.tsx

+        popoverClassName,
+    );
+
+    const defaultAutoFocus = isHoverInteractionKind ? false : undefined;


question: What is the difference between false and undefined here?

This logic was originally defined in the original Popover component here:

blueprint/packages/core/src/components/popover/popover.tsx

Line 415 in d8783f0

const defaultAutoFocus = this.isHoverInteractionKind() ? false : undefined;

My understanding of this is that for hover interactions, we want to explicitly disable auto-focus (false) because we don't want hover to steal focus from the user's current input. For click interactions, we want to use the default behavior which likely enables auto-focus when appropriate.

svc-palantir-github · 2025-09-25T20:39:57Z

[CR] Simplify middleware placement logic

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

Replace createRef with useRef for targetRef to maintain ref persistence across re-renders

svc-palantir-github · 2025-09-25T20:59:56Z

[CR] Use `useRef` instead of `createRef` for targetRef in PopoverNext

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-10-10T20:11:39Z

Split `minimal` prop into new `arrow` and `animation` props

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-10-10T20:58:35Z

Split `minimal` prop into new `arrow` and `animation` props

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

svc-palantir-github · 2025-10-13T15:45:51Z

Set `enforceFocus` to false in PopoverNext example

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

ggdouglas added Package: core no changelog labels Sep 18, 2025

ggdouglas force-pushed the gdouglas/popover-next branch from 5706459 to 7b8f84d Compare September 18, 2025 01:52

ggdouglas force-pushed the gdouglas/popover-next branch from 7b8f84d to e7e0cfe Compare September 18, 2025 17:12

ggdouglas added 3 commits September 19, 2025 16:15

Install @floating-ui/react dependency in core

c255f36

Create PopoverNext component as new Popover implementation

c3bce1c

Write docs for PopoverNext and add examples

8db1447

ggdouglas force-pushed the gdouglas/popover-next branch from e7e0cfe to 8db1447 Compare September 19, 2025 20:15

ggdouglas marked this pull request as ready for review September 19, 2025 20:15

invliD reviewed Sep 24, 2025

View reviewed changes

ggdouglas added 2 commits September 24, 2025 21:54

[CR] Edit comments/markdown

fce1b5d

[CR] Simplify boolean expression in PopoverTarget

bef744a

ggdouglas added 2 commits September 24, 2025 22:12

[CR] Handle empty strings in cssPropertyToString

5eb0a2b

[CR] Remove redundant interactionKind default in PopoverTarget

62ee536

ggdouglas added 3 commits September 25, 2025 11:05

[CR] Define exact props for PopoverTarget and PopoverPopup components

dbf5012

[CR] Explicitly redefine props for PopoverNext

0080141

[CR] Redeclare new Placement type within Blueprint

7dd3241

mm-wang reviewed Sep 25, 2025

View reviewed changes

ggdouglas added 2 commits September 25, 2025 16:27

[CR] Simplify middleware placement logic

06463f9

Remove optional chaining from middleware config

9b3be13

[CR] Use useRef instead of createRef for targetRef in PopoverNext

2909091

Replace createRef with useRef for targetRef to maintain ref persistence across re-renders

Split minimal prop into new arrow and animation props

86cd4c0

ggdouglas force-pushed the gdouglas/popover-next branch from 3ab8cbf to 86cd4c0 Compare October 10, 2025 20:41

Set enforceFocus to false in PopoverNext example

367719e

	const SUBMENU_POPOVER_MODIFIERS: PopoverProps["modifiers"] = {
	// 20px padding - scrollbar width + a bit
	flip: { enabled: true, options: { padding: 20, rootBoundary: "viewport" } },
	// shift popover up 5px so MenuItems align
	offset: { enabled: true, options: { offset: [-5, 0] } },
	preventOverflow: { enabled: true, options: { padding: 20, rootBoundary: "viewport" } },
	};

	modifiers={{
	arrow: {
	enabled: !this.props.minimal,
	},
	offset: {
	options: {
	offset: [0, TOOLTIP_ARROW_SVG_SIZE / 2],
	},
	},
	}}

feat: Add PopoverNext component built on Floating UI #7573

Are you sure you want to change the base?

feat: Add PopoverNext component built on Floating UI #7573

Uh oh!

Conversation

ggdouglas commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Migration

Follow-ups

References

Uh oh!

svc-palantir-github commented Sep 18, 2025

Write docs for PopoverNext and add examples

Uh oh!

svc-palantir-github commented Sep 18, 2025

Write docs for PopoverNext and add examples

Uh oh!

svc-palantir-github commented Sep 18, 2025

Write docs for PopoverNext and add examples

Uh oh!

svc-palantir-github commented Sep 19, 2025

Write docs for PopoverNext and add examples

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

invliD Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

ggdouglas Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

invliD Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

ggdouglas Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

invliD Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

svc-palantir-github commented Sep 25, 2025

[CR] Edit comments/markdown

Uh oh!

svc-palantir-github commented Sep 25, 2025

[CR] Remove redundant `interactionKind` default in `PopoverTarget`

Uh oh!

svc-palantir-github commented Sep 25, 2025

[CR] Redeclare new Placement type within Blueprint

Uh oh!

mm-wang left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mm-wang Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mm-wang Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

ggdouglas Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

svc-palantir-github commented Sep 25, 2025

[CR] Simplify middleware placement logic

Uh oh!

svc-palantir-github commented Sep 25, 2025

[CR] Use `useRef` instead of `createRef` for targetRef in PopoverNext

Uh oh!

ggdouglas commented Sep 18, 2025 •

edited

Loading

ggdouglas Oct 10, 2025 •

edited

Loading