WIP: feat(react-headless-components-preview): add Popover & positioning by mainframev · Pull Request #36006 · microsoft/fluentui

mainframev · 2026-04-20T00:51:52Z

Adds a headless Popover (Popover, PopoverTrigger, PopoverSurface) to the @fluentui/react-headless-components-preview package, positioned via the native CSS Anchor Positioning API instead of floating-ui

Feature with v9 `@fluentui/react-popover`

v9 feature	Status
`open` / `defaultOpen` / `onOpenChange`	✅
`openOnHover` + `mouseLeaveDelay`	✅
`openOnContext` (right-click, cursor-anchored)	✅
`withArrow` (+ consumer-owned arrow CSS via `[data-placement]`)	⚠️ User provides styles for arrow based on data-placement and data-arrow attributes
`trapFocus` + `aria-modal` / `role="dialog"`	✅ (via `useFocusScope`)
`disableAutoFocus`	✅
`closeOnScroll`, `closeOnIframeFocus`	✅
`inline` (skip top-layer)	⚠️ v9: skips the `<Portal>` wrapper - DOM placement only, positioning math unchanged. Headless: skips HTML Popover API top-layer promotion, also changes the overflow boundary CSS `position-try-fallbacks` flips against (viewport → nearest + scroll port / containing block)
`mountNode` (portal target)	✅
Nested popovers (per-instance Escape / dismiss)	✅
`positioning.position` + `positioning.align`	✅
`positioning.offset` (number or `{ mainAxis, crossAxis }`)	✅
`positioning.coverTarget`	✅
`positioning.fallbackPositions`	✅
`positioning.autoSize` (`true` / `'width'` / `'height'`)	❌ Not implemented
`positioning.overflowBoundary`	✅
`positioning.overflowBoundaryPadding`	❌ Not implemented
`positioning.overflowBoundaryRect`	❌ Not implemented
`positioning.matchTargetSize: 'width'`	✅
`positioning.strategy: 'absolute' \| 'fixed'`	✅
`positioning.pinned`	✅
`positioning.target` (custom anchor)	✅
`positioning.positioningRef` (imperative `setTarget`)	✅
`flipBoundary`	❌ Not implemented
`arrowPadding`	➖ Configurable on user side via styles
`shiftToCoverTarget`	❌ Not implemented
`onPositioningEnd`	➖ Native API has no "settle" event
`disableUpdateOnResize`	➖ Native anchor positioning + targeted usage is always-on
`useTransform`	➖ Native anchor positioning doesn't use transform, no conceptual equivalent

Related Issue(s)

Partially implements RFC: Headless Components (@fluentui/react-headless-components) #35984

github-actions · 2026-04-20T01:02:50Z

Pull request demo site: URL

github-actions · 2026-04-20T01:59:41Z

📊 Bundle size report

Package & Exports	Baseline (minified/GZIP)	PR	Change
`react-headless-components-preview` react-headless-components-preview: entire library	`70.65 kB` `20.862 kB`	`88.57 kB` `26.636 kB`	`17.92 kB` `5.774 kB`

_{🤖 This report was generated against 86cf4cbebfc9517e2373ce8077674bbcaf3ce7da}

…n native CSS anchor positioning

…ybook stories

…n spec-pure CSS anchor positioning

`useDialogContextValues copy.ts` was an editor artifact that slipped into the feature commit. Removing it leaves `useDialogContextValues.ts` untouched.

…oning on spec-pure CSS anchor positioning

dmytrokirpa · 2026-04-23T14:12:01Z

+
+export type PositioningReturn = {
+  targetRef: React.RefCallback<HTMLElement>;
+  containerRef: React.RefCallback<HTMLElement>;


should this be surfaceRef or is it for consistency with v9?

dmytrokirpa · 2026-04-23T14:12:46Z

+import { computeAvailableHeight, computeAvailableWidth, resolveBoundaryPadding, resolveElementRef } from './utils';
+
+export type UseBoundaryClampOptions = {
+  overflowBoundary: PositioningProps['overflowBoundary'];


would be great to document the exported props and hooks

dmytrokirpa · 2026-04-23T14:16:16Z

+function mountHook(options: PositioningProps = {}) {
+  const resultRef = React.createRef<{ current: PositioningReturn }>();
+  const Capture = () => {
+    const result = usePositioning(options);


nit, but we can probably type-cast once if it's really needed

Suggested change

const result = usePositioning(options);

const result = usePositioning(options) as unknown as { current: PositioningReturn };

dmytrokirpa · 2026-04-23T14:19:21Z

+    result.current.containerRef(node);
+
+    expect(node.style.getPropertyValue('position-anchor')).toMatch(/^--popover-anchor-/);
+    expect(node.style.getPropertyValue('position-area')).toBe('block-end span-inline-end');


nit, but we can use the https://github.com/testing-library/jest-dom#tohavestyle to make it a bit cleaner

Suggested change

expect(node.style.getPropertyValue('position-area')).toBe('block-end span-inline-end');

expect(node).toHaveStyle({ positionArea: 'block-end span-inline-end' });

dmytrokirpa · 2026-04-23T14:20:38Z

+    const node = document.createElement('div');
+    result.current.containerRef(node);
+
+    expect(node.style.position).toBe('absolute');


nit, but can be combined to one assertion for all styles

dmytrokirpa · 2026-04-23T14:21:03Z

as discussed offline, we'll need to remove this for now

dmytrokirpa · 2026-04-23T14:27:07Z

+  const childProps = (child?.props ?? {}) as Record<string, unknown>;
+
+  const triggerChildProps = {
+    'aria-expanded': `${open}` as 'true' | 'false',


Why don't we use the popovertarget attribute https://developer.mozilla.org/en-US/docs/Web/API/Popover_API#html_attributes?

current implementation uses showPopover() and I found it more suitable as we need to also show Popover on hover (v9 canonical Popover has that feature), have it controlled and uncontrolled, mouseLeaveDelay for openOnHover etc

dmytrokirpa · 2026-04-23T14:32:47Z

+
+  const positioning = usePositioning(resolvePositioningShorthand(props.positioning));
+
+  useOnClickOutside({


just to confrim, did you check if Popover API has this functionality out-of-the-box?

it does, but only when popover has popover='auto' / popover attribute, which has native dismiss on Esc and overlay click, great that it works also with nested popovers, but in current implementation it uses manual, which does not have such functionality out of the box, because we need multiple non-nested Popovers to be opened. I think auto will be a great fit to Tooltip

dmytrokirpa · 2026-04-23T14:33:30Z

+    disabledFocusOnIframe: !closeOnIframeFocus,
+  });
+
+  useOnScrollOutside({


the same question as above, pls double check if we can drop this in favor of Popover API

dmytrokirpa · 2026-04-23T14:34:48Z

+ * for the breathing-room `GAP`. Used by `useAutoSizeBoundary` to derive a
+ * numeric `max-height` when `overflowBoundary` is supplied.
+ */
+export function computeAvailableHeight(


lets cover these utils with unit tests, should be straightforward as they are stateless

mainframev self-assigned this Apr 20, 2026

mainframev added Component: Popover Component: PopoverSurface Area: Positioning Headless labels Apr 20, 2026

microsoft-github-policy-service Bot added the PR: API Modified label Apr 20, 2026

mainframev force-pushed the feat/headless-popover-v2 branch from f26ae3e to 22f36ba Compare April 20, 2026 00:55

mainframev force-pushed the feat/headless-popover-v2 branch from 22f36ba to e9fef9d Compare April 20, 2026 01:46

mainframev force-pushed the feat/headless-popover-v2 branch 12 times, most recently from 58218ca to c32d139 Compare April 22, 2026 10:30

mainframev changed the title ~~WIP: feat(react-headless-components-preview): add Popover & positioning~~ feat(react-headless-components-preview): add Popover & positioning Apr 22, 2026

mainframev marked this pull request as ready for review April 22, 2026 10:42

mainframev requested review from a team as code owners April 22, 2026 10:42

mainframev requested a review from dmytrokirpa April 22, 2026 10:47

mainframev added 3 commits April 22, 2026 14:21

feat(react-headless-components-preview): add headless Popover built o…

d1202ff

…n native CSS anchor positioning

docs(react-headless-components-preview): add Popover Storybook stories

5517dce

docs(react-headless-components-preview): add Positioning concept Stor…

4dce4b8

…ybook stories

refactor(react-headless-components-preview): rebuild usePositioning o…

a5c689e

…n spec-pure CSS anchor positioning

mainframev force-pushed the feat/headless-popover-v2 branch from c32d139 to 4774cce Compare April 22, 2026 12:21

mainframev requested a review from a team as a code owner April 22, 2026 12:21

docs(headless): add Popover spec

0022e71

mainframev force-pushed the feat/headless-popover-v2 branch 2 times, most recently from 60d79ff to 30490b7 Compare April 22, 2026 13:18

chore(react-dialog): remove accidentally committed duplicate file

f4a8375

`useDialogContextValues copy.ts` was an editor artifact that slipped into the feature commit. Removing it leaves `useDialogContextValues.ts` untouched.

mainframev force-pushed the feat/headless-popover-v2 branch from 30490b7 to f4a8375 Compare April 22, 2026 13:29

mainframev added 2 commits April 22, 2026 21:02

fixup! refactor(react-headless-components-preview): rebuild usePositi…

a8bffc5

…oning on spec-pure CSS anchor positioning

fixup! refactor(react-headless-components-preview): rebuild usePositi…

8db0ab2

…oning on spec-pure CSS anchor positioning

mainframev marked this pull request as draft April 22, 2026 22:16

mainframev force-pushed the feat/headless-popover-v2 branch 2 times, most recently from 0da03bc to c16a425 Compare April 23, 2026 02:33

mainframev marked this pull request as ready for review April 23, 2026 09:35

fixup! refactor(react-headless-components-preview): rebuild usePositi…

e42cb0f

…oning on spec-pure CSS anchor positioning

mainframev force-pushed the feat/headless-popover-v2 branch from c16a425 to e42cb0f Compare April 23, 2026 12:42

mainframev marked this pull request as draft April 23, 2026 13:18

dmytrokirpa reviewed Apr 23, 2026

View reviewed changes

mainframev changed the title ~~feat(react-headless-components-preview): add Popover & positioning~~ WIP: feat(react-headless-components-preview): add Popover & positioning Apr 24, 2026

	const result = usePositioning(options);
	const result = usePositioning(options) as unknown as { current: PositioningReturn };

	expect(node.style.getPropertyValue('position-area')).toBe('block-end span-inline-end');
	expect(node).toHaveStyle({ positionArea: 'block-end span-inline-end' });


		const positioning = usePositioning(resolvePositioningShorthand(props.positioning));

		useOnClickOutside({

Conversation

mainframev commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Feature with v9 @fluentui/react-popover

Related Issue(s)

Uh oh!

github-actions Bot commented Apr 20, 2026

Uh oh!

github-actions Bot commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Bundle size report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmytrokirpa Apr 23, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

mainframev Apr 23, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

mainframev Apr 23, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mainframev commented Apr 20, 2026 •

edited

Loading

Feature with v9 `@fluentui/react-popover`

github-actions Bot commented Apr 20, 2026 •

edited

Loading

dmytrokirpa Apr 23, 2026 •

edited

Loading

mainframev Apr 23, 2026 •

edited

Loading

mainframev Apr 23, 2026 •

edited

Loading