Skip to content

feat: add useScrollAnchor - #8753

Open
tay1orjones wants to merge 5 commits into
mainfrom
tay1orjones-safari-scroll-preservation
Open

tay1orjones wants to merge 5 commits into
mainfrom
tay1orjones-safari-scroll-preservation

Conversation

@tay1orjones

@tay1orjones tay1orjones commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Closes github/primer#6306

Keep the comment you're reading in place when earlier content loads, including in browsers without native scroll anchoring. useScrollAnchor is opt-in, so existing consumers are unchanged.

Changelog

New

  • useScrollAnchor({container, anchor, anchorKey}) preserves an element's viewport position as its container changes.
  • An interactive Storybook demo and hook API documentation.

Changed

Removed

Rollout strategy

  • No changes needed in github/github-ui
  • Needs changes in github/github-ui
  • Ships with feature flag(s)
  • Not sure
  • None

Adoption plan: IssueTimeline supplies the timeline container and a visible comment using callback refs, owns anchor selection, and reconciles its existing Safari workaround. Upgrading Primer alone won't change timeline behavior.

Testing & Reviewing

Open Hooks/useScrollAnchor → Scroll Anchor. Scroll to the highlighted comment, load earlier comments, and toggle the hook to compare. Native scroll anchoring is disabled in the demo to isolate the hook's behavior. Only window scrolling is supported.

Real Safari scrolling and hash-navigation behavior still need verification.

Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@changeset-bot

changeset-bot Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 0d5889b

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 github-actions Bot added the integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm label Nov 13, 2026
@github-actions

Copy link
Copy Markdown
Contributor

⚠️ 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.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@primer-integration

primer-integration Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Integration test results from github/github-ui PR:

Waiting  Changes   Waiting
Passed  CI   Passed
Passed  VRT   Passed
Passed  Projects   Passed

@github-actions github-actions Bot added the integration-tests: passing Changes in this PR do NOT cause breaking changes in gh/gh label Nov 16, 2026
@tay1orjones tay1orjones changed the title feat: add useScrollAnchor with an interactive demo feat: add useScrollAnchor Nov 16, 2026
@tay1orjones
tay1orjones marked this pull request as ready for review November 16, 2026 22:40
@tay1orjones
tay1orjones requested a review from a team as a code owner November 16, 2026 22:40
@tay1orjones
tay1orjones requested review from joshblack and a balanced review from Copilot November 16, 2026 22:40

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Scroll anchoring can miss late-mounted refs and layout-only growth, while anchor changes and animated or clamped scrolling can produce incorrect compensation.

5 open issues
What changed in this PR

Adds an opt-in useScrollAnchor hook to Primer React that preserves a selected element’s viewport position during container DOM changes. It supports window scrolling and leaves existing consumers unchanged.

Changes:

  • Adds the hook, settings type, and public exports.
  • Adds API documentation and an interactive demo with native anchoring disabled.
  • Adds focused tests, an export snapshot update, and a minor-release changeset.
File Description
packages/​react/​src/​stories/​useScrollAnchor.stories.tsx Demonstrates loading earlier comments and toggling anchoring.
packages/​react/​src/​stories/​ScrollAnchor.stories.module.css Styles the demo timeline and sticky controls.
packages/​react/​src/​index.ts Exports the hook and settings type publicly.
packages/​react/​src/​hooks/​useScrollAnchor.ts Implements mutation-driven scroll compensation.
packages/​react/​src/​hooks/​useScrollAnchor.hookDocs.json Documents the refs and window-scrolling scope.
packages/​react/​src/​hooks/​index.ts Adds hook-barrel exports.
packages/​react/​src/​hooks/​__tests__/​useScrollAnchor.test.tsx Tests compensation, user scrolling, and anchor replacement.
packages/​react/​src/​__tests__/​__snapshots__/​exports.test.ts.snap Records the new public exports.
.changeset/​safari-scroll-anchor.md Declares the new API as a minor release.

Review effort: Balanced

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

Copy link
Copy Markdown
Contributor

⚠️ Action required

👋 Hi, there are new commits since the last successful integration test. 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.

@joshblack joshblack left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tay1orjones random, since scroll anchoring is baseline 2026 do you think this is something we could just enable and be okay with the jump in older browsers? Wasn't sure what your thoughts were, obviously would be great if this "just worked" versus needing to wire it up but makes sense if folks need this directly.

@tay1orjones

Copy link
Copy Markdown
Contributor Author

@joshblack yeah I thought the same but github-ui turned it off earlier this year, even for other browsers, https://github.com/github/github-ui/pull/17499.

If we wanted to go native, we'd need to update github-ui to fix those remaining gaps:

  1. Keys for remounted rows in github-ui aren't stable, so react re-renders replace nodes which native can't handle. We'd need to stabilize the page keys (or drop the page wrappers), and remove overflow-anchor: none.
  2. With native, the browser anchors to the first visible element, not the highlighted comment. So we'd need to have a hook or something that keeps a chosen anchor, like the highlighted comment, in place.

Ultroncn

This comment was marked as off-topic.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

This comment was marked as resolved.

@tay1orjones tay1orjones added the integration-tests: skipped manually Changes in this PR do not require an integration test label Nov 19, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

This comment was marked as resolved.

This branch was successfully deployed

2 active deployments
storybook-preview-8753 — 0d5889bd Deployed Nov 19, 2026 by github-actions[bot]
github-pages — 0d5889bd Deployed Nov 19, 2026 by tay1orjones via deploy-preview #34457
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

integration-tests: passing Changes in this PR do NOT cause breaking changes in gh/gh integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm integration-tests: skipped manually Changes in this PR do not require an integration test

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants