Repository navigation
feat: add useScrollAnchor - #8753
tay1orjones wants to merge 5 commits into
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
🦋 Changeset detectedLatest commit: 0d5889b The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
|
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
Integration test results from github/github-ui PR: |
There was a problem hiding this comment.
🟡 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
Reattach observers when referenced nodes become available · New Observe layout-only changes to keep the anchor position stable · New Reset the baseline when switching selected anchors · New Force layout-compensation scroll corrections to be instant · New Re-measure the anchor after scroll clamping · New
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>
|
joshblack
left a comment
There was a problem hiding this comment.
@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.
|
@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:
|
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This comment was marked as resolved.
This comment was marked as resolved.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Closes github/primer#6306
Keep the comment you're reading in place when earlier content loads, including in browsers without native scroll anchoring.
useScrollAnchoris opt-in, so existing consumers are unchanged.Changelog
New
useScrollAnchor({container, anchor, anchorKey})preserves an element's viewport position as its container changes.Changed
Removed
Rollout strategy
Adoption plan:
IssueTimelinesupplies 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