AnchoredOverlay: Add support for CSS anchor positioning by TylerJDev · Pull Request #7604 · primer/react

TylerJDev · 2026-02-26T22:22:43Z

Closes https://github.com/github/primer/issues/6446

The first batch of work to add CSS anchor positioning to overlay components.

Example of CSS anchor positioning:

Screen.Recording.2026-03-04.at.7.33.32.AM.mov

Video description

In the video, we show the `AnchoredOverlay` opening and being positioned directly under the trigger. We then show off the overlay repositioning when there's lack of space.

Changelog

New

Added support for CSS Anchor Positioning in AnchoredOverlay, gated by the primer_react_css_anchor_positioning feature flag.
Updated ActionMenu to ensure that the anchor button receives the correct anchor class for CSS anchor positioning, and improved merging of class names between anchor and button props.
Added new stories to AnchoredOverlay.features.stories.tsx to demonstrate anchor positioning in various layouts, including centered overlays, grid layouts, within dialogs (including nested and overflowing dialogs), scroll containers, and sticky headers.

Rollout strategy

Patch release
Minor release
Major release; if selected, include a written rollout or migration plan
None; if selected, include a brief description as to why

Testing & Reviewing

Merge checklist

Added/updated tests
Added/updated documentation
Added/updated previews (Storybook)
Changes are SSR compatible
Tested in Chrome
Tested in Firefox
Tested in Safari
Tested in Edge
(GitHub staff only) Integration tests pass at github/github-ui (Learn more about how to run integration tests)

changeset-bot · 2026-02-26T22:22:47Z

🦋 Changeset detected

Latest commit: 452d29e

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

This PR includes changesets to release 1 package

Name	Type
@primer/react	Minor

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

github-actions · 2026-02-26T22:23:17Z

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Or, apply the integration-tests: skipped manually label to skip these checks.

primer · 2026-02-26T22:29:59Z

🤖 Lint and formatting issues have been automatically fixed and committed to this PR.

primer · 2026-02-26T22:37:00Z

🤖 Lint issues have been automatically fixed and committed to this PR.

primer · 2026-02-26T23:12:08Z

🤖 Lint issues have been automatically fixed and committed to this PR.

primer · 2026-02-27T02:06:32Z

🤖 Lint and formatting issues have been automatically fixed and committed to this PR.

primer · 2026-02-27T02:13:35Z

🤖 Lint issues have been automatically fixed and committed to this PR.

primer · 2026-02-27T02:41:55Z

🤖 Lint issues have been automatically fixed and committed to this PR.

Copilot

Pull request overview

This PR adds CSS Anchor Positioning support to AnchoredOverlay, gated behind the primer_react_css_anchor_positioning feature flag. When enabled, the overlay uses native CSS anchor positioning (with a polyfill for unsupported browsers) instead of JS-based positioning via a portal. This allows overlays within dialogs, sticky elements, and scroll containers to position correctly. The @oddbird/css-anchor-positioning polyfill is added as a runtime dependency.

Changes:

CSS Anchor Positioning feature flag and core logic added to AnchoredOverlay and Overlay components
ActionMenu updated to properly merge className from anchor props with user-provided class names
New Storybook stories demonstrating anchor positioning in various layouts (grids, dialogs, scroll containers, sticky headers)

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx`	Core logic: adds CSS anchor positioning path, polyfill invocation, Wrapper div, anchor/overlay class application
`packages/react/src/AnchoredOverlay/AnchoredOverlay.module.css`	New CSS classes: `.Wrapper` (anchor-scope), `.Anchor` (anchor-name), `.AnchoredOverlay` (anchor position + side-specific layout rules)
`packages/react/src/Overlay/Overlay.tsx`	Skips portal when flag is on; sets `data-anchor-position` attribute for all Overlay instances
`packages/react/src/Overlay/Overlay.module.css`	Gates `top/left/right/bottom` CSS var positioning on `[data-anchor-position='false']`
`packages/react/src/FeatureFlags/DefaultFeatureFlags.ts`	Adds `primer_react_css_anchor_positioning` flag (default: false)
`packages/react/src/ActionMenu/ActionMenu.tsx`	Merges anchor className (including `classes.Anchor`) with user-provided classNames for all anchor path types
`packages/react/src/ActionMenu/ActionMenu.test.tsx`	Tests verify `classes.Anchor` is applied to anchor/button elements
`packages/react/src/AnchoredOverlay/AnchoredOverlay.features.stories.tsx`	New stories demonstrating CSS anchor positioning in various layout scenarios
`packages/react/src/AnchoredOverlay/AnchoredOverlay.features.stories.module.css`	New CSS for story layouts
`packages/react/src/ActionMenu/ActionMenu.examples.stories.tsx`	New stories for centered ActionMenu and two-menu scenario
`packages/react/package.json`	Adds `@oddbird/css-anchor-positioning` as a runtime dependency
`package-lock.json`	Lock file updates for new dependencies
`.changeset/nine-buttons-lose.md`	Minor release changeset for the feature

Comments suppressed due to low confidence (1)

packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx:241

When cssAnchorPositioning is enabled, the overlay becomes immediately visible (visibility={cssAnchorPositioning || position ? 'visible' : 'hidden'}), but useFocusTrap and useFocusZone are still gated on !open || !position. This means on the first render when position hasn't been calculated yet, the overlay is visible but the focus trap is not active. This can cause an accessibility gap where keyboard users can navigate out of the overlay before the focus trap activates.

The disabled condition for useFocusTrap and useFocusZone should be updated to account for CSS anchor positioning: when cssAnchorPositioning is true, the focus should be trapped as soon as the overlay is open (disabled: !open), rather than waiting for the JS-calculated position.

  useFocusZone({
    containerRef: overlayRef,
    disabled: !open || !position,
    ...focusZoneSettings,
  })
  useFocusTrap({containerRef: overlayRef, disabled: !open || !position, ...focusTrapSettings})

packages/react/src/AnchoredOverlay/AnchoredOverlay.features.stories.tsx

packages/react/src/AnchoredOverlay/AnchoredOverlay.module.css

packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx

packages/react/src/Overlay/Overlay.tsx

packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx

siddharthkp · 2026-03-05T13:23:09Z

packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx

 import {type ResponsiveValue} from '../hooks/useResponsiveValue'
 import {IconButton, type IconButtonProps} from '../Button'
 import {XIcon} from '@primer/octicons-react'
+import polyfill from '@oddbird/css-anchor-positioning/fn'


Does this mean the polyfill is already part of the bundle?

Yeah! We had some of the polyfill's dependencies already (i.e., floating-ui), which is good since we're already accounting for those in our current bundle size.

Oh that's interesting. I realised we no longer have a comment from the size action. Would be good to have a number before we merge.

It does run but not sure what the results are 😅

https://github.com/primer/react/actions/runs/22721918648/job/65886127997?pr=7604

Having Copilot take a stab at this here: #7628. Looks like we deleted the size.yml which added the comment. This adds it back 🤔

siddharthkp · 2026-03-05T13:23:27Z

packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx

-  }, [open, overlayRef, updateOverlayRef])
+
+    if (cssAnchorPositioning && open) {
+      applyAnchorPositioningPolyfill()


Should we wait for open or load it already if we know we will need it?

Maybe just load? 🤔 I'll go ahead and remove the open from the conditional!

siddharthkp · 2026-03-05T13:25:07Z

packages/react/src/Overlay/Overlay.module.css

+    bottom: var(--bottom, auto);
+  }
+
+  &[data-anchor-position='false']:not([data-responsive='fullscreen']) {


bonus bugfix hiding in this PR?

Hah, yeah - we explicitly set the top and left to 0 when fullscreen is used, so without this it would get overridden.

siddharthkp

Very nice work!

The direction looks perfect, left a few clarifying questions

TylerJDev · 2026-03-05T16:33:13Z

@siddharthkp - should be ready for another review! I addressed some feedback, and am working on the size report in #7628 😁

primer-integration · 2026-03-05T19:21:16Z

👋 Hi from github/github-ui! Your integration PR is ready: https://github.com/github/github-ui/pull/15261

primer-integration · 2026-03-05T19:27:25Z

Integration test results from github/github-ui:

CI Failed
VRT Passed
Projects Waiting

CI check runs linting, type checking, and unit tests. Check the workflow logs for specific failures.

Need help? If you believe this failure is unrelated to your changes, please reach out to the Primer team for assistance.

TylerJDev added 7 commits February 20, 2026 14:20

Init tests

cad3f82

Add back fixed

89c1fe9

Add feature flag

c6dd31c

Add data-*

eea8dd5

Fix data-*

b05fca7

Add outside sides

7ba9406

Add as default true for test

794f280

github-actions bot added staff Author is a staff member integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm labels Feb 26, 2026

chore: auto-fix lint and formatting issues

8368f2b

github-actions bot temporarily deployed to storybook-preview-7604 February 26, 2026 22:32 Inactive

primer bot deployed to github-pages February 26, 2026 22:41 View deployment

github-actions bot temporarily deployed to storybook-preview-7604 February 26, 2026 22:41 Inactive

Merge branch 'main' into tylerjdev/css-anchor-positioning

bafd606

TylerJDev had a problem deploying to github-pages February 26, 2026 23:16 — with GitHub Actions Failure

github-actions bot temporarily deployed to storybook-preview-7604 February 26, 2026 23:16 Inactive

TylerJDev and others added 2 commits February 26, 2026 20:58

Add scope

281f48b

chore: auto-fix lint and formatting issues

c8dbbff

github-actions bot temporarily deployed to storybook-preview-7604 February 27, 2026 02:10 Inactive

primer bot deployed to github-pages February 27, 2026 02:20 View deployment

github-actions bot temporarily deployed to storybook-preview-7604 February 27, 2026 02:21 Inactive

Fix scope

8c7d5e4

github-actions bot temporarily deployed to storybook-preview-7604 March 3, 2026 21:53 Inactive

test(vrt): update snapshots

d310e7c

github-actions bot removed the update snapshots 🤖 Command that updates VRT snapshots on the pull request label Mar 3, 2026

primer bot deployed to github-pages March 3, 2026 22:13 View deployment

github-actions bot temporarily deployed to storybook-preview-7604 March 3, 2026 22:13 Inactive

Merge branch 'main' into tylerjdev/css-anchor-positioning

4b51d94

TylerJDev deployed to github-pages March 3, 2026 22:34 — with GitHub Actions View deployment

github-actions bot temporarily deployed to storybook-preview-7604 March 3, 2026 22:35 Inactive

TylerJDev added the update snapshots 🤖 Command that updates VRT snapshots on the pull request label Mar 3, 2026

github-actions bot removed the update snapshots 🤖 Command that updates VRT snapshots on the pull request label Mar 3, 2026

Merge branch 'main' into tylerjdev/css-anchor-positioning

d66c451

TylerJDev deployed to github-pages March 4, 2026 13:43 — with GitHub Actions View deployment

github-actions bot temporarily deployed to storybook-preview-7604 March 4, 2026 13:44 Inactive

Reset .playwright snapshots to main

64633ff

TylerJDev deployed to github-pages March 4, 2026 13:59 — with GitHub Actions View deployment

github-actions bot temporarily deployed to storybook-preview-7604 March 4, 2026 13:59 Inactive

TylerJDev marked this pull request as ready for review March 4, 2026 22:13

TylerJDev requested a review from a team as a code owner March 4, 2026 22:13

Copilot AI reviewed Mar 4, 2026

View reviewed changes

siddharthkp reviewed Mar 5, 2026

View reviewed changes

TylerJDev added 4 commits March 5, 2026 07:13

Address feedback

14d7efb

Fix ActionMenu test

af4ebbb

Adjust CSS selector

3b881eb

Adjust data selector

452d29e

Conversation

TylerJDev commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog

New

Rollout strategy

Testing & Reviewing

Merge checklist

Uh oh!

changeset-bot bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Feb 26, 2026

⚠️ Action required

Uh oh!

primer bot commented Feb 26, 2026

Uh oh!

primer bot commented Feb 26, 2026

Uh oh!

primer bot commented Feb 26, 2026

Uh oh!

primer bot commented Feb 27, 2026

Uh oh!

primer bot commented Feb 27, 2026

Uh oh!

primer bot commented Feb 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

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!

siddharthkp left a comment

Choose a reason for hiding this comment

Uh oh!

TylerJDev commented Mar 5, 2026

Uh oh!

primer-integration bot commented Mar 5, 2026

Uh oh!

primer-integration bot commented Mar 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

TylerJDev commented Feb 26, 2026 •

edited

Loading

changeset-bot bot commented Feb 26, 2026 •

edited

Loading