AnchoredOverlay: Allow customization of CSS anchor positioning

[TylerJDev]

Adds cssAnchorPositioningSettings prop to AnchoredOverlay so consumers can control how the overlay behaves when native CSS anchor positioning is active.

When CSS anchor positioning is active, the overlay relies on the stylesheet defined position-try-fallbacks list on .AnchoredOverlay, which can flip the overlay to sides the consumer may not want. This prop lets consumers opt into other fallback behavior via a fallbackStrategy:

• "default" - use the built-in CSS fallback rules (current behavior).
• "none" - keep the requested side with no CSS fallbacks (position-try-fallbacks: none).
• "opposite-side" - only allow flipping to the opposite side along the relevant axis (flip-block for outside-top/outside-bottom, flip-inline for outside-left/outside-right).

The setting is applied as an inline position-try-fallbacks style on the overlay element while it is open, and ignored entirely when CSS anchor positioning is not active.

Changelog

New

• cssAnchorPositioningSettings?: { fallbackStrategy: 'default' | 'none' | 'opposite-side' } prop on AnchoredOverlay.

Changed

• When the overlay opens with CSS anchor positioning active, it now writes/removes the inline position-try-fallbacks property based on cssAnchorPositioningSettings. Existing callers that don't pass the prop default to "default", preserving current behavior.
• Adds default behavior for inside-* sides. CSS anchor positioning doesn't natively support them, so this ensures that CSS anchor positioning does not break when used.

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

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 66ae2f5

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]

⚠️ 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. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

To publish a canary release for integration testing, apply the Canary Release label to this PR.

[primer]

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

[Copilot]

Pull request overview

Adds a new consumer-facing prop on AnchoredOverlay to control native CSS anchor positioning fallback behavior by writing position-try-fallbacks inline when CSS anchor positioning is active.

Changes:

• Adds cssAnchorPositioningSettings prop and applies/removes inline position-try-fallbacks while the overlay is open (CSS anchor positioning path only).
• Extends CSS anchor-positioning selectors to handle inside-*data-side values.
• Adds unit tests for the new fallback strategies and updates Storybook stories + adds a changeset.

Show a summary per file

File	Description
packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx	Adds the new prop, writes/removes inline position-try-fallbacks, and introduces helper to compute fallback values.
packages/react/src/AnchoredOverlay/AnchoredOverlay.test.tsx	Adds tests asserting the inline position-try-fallbacks behavior for none / opposite-side and that it’s ignored when CSS anchor positioning is disabled.
packages/react/src/AnchoredOverlay/AnchoredOverlay.module.css	Extends CSS anchor positioning rules so inside-* sides don’t break when CSS anchor positioning is active.
packages/react/src/AnchoredOverlay/AnchoredOverlay.features.stories.tsx	Updates a features story to pass cssAnchorPositioningSettings.
packages/react/src/AnchoredOverlay/AnchoredOverlay.dev.stories.tsx	Adds dev stories/demos for the new fallback strategies (grid scenarios).
.changeset/anchored-overlay-css-anchor-positioning-settings.md	Declares a minor bump for the new public prop.

Copilot's findings

• Files reviewed: 6/6 changed files
• Comments generated: 2

[Copilot]

Copilot's findings

• Files reviewed: 6/6 changed files
• Comments generated: 2

[primer]

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

[liuliu-dev]

[primer-integration]

Integration test results from github/github-ui PR:

CI Passed
VRT Waiting
Projects Running