UI: Prevent docs page scroll reset on HMR re-render

[LongTangGithub]

Closes #26060

What I did

Fixed a bug where hot-reloading a story or MDX file while scrolled down on a docs page
causes the page to jump back to the top.

WebView.prepareForDocs() was unconditionally resetting scrollTop/scrollLeft to 0 on every docs render, including HMR re-renders. The scroll reset is only appropriate when navigating to a new docs page (story or view mode changed), not when the same page reloads due to HMR.

Fix:

• Added a scrollReset option to prepareForDocs() (defaulting to true for backwards compatibility).
• PreviewWithSelection now passes scrollReset: storyIdChanged || viewModeChanged, so scroll only resets on actual navigation, not HMR.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

Caution

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

1. Compile, clear cache, and start Storybook:

   yarn nx compile core --skip-nx-cache
   rm -rf code/node_modules/.cache/storybook
   cd code && yarn storybook:ui

2. In Chrome, navigate to Addons → Docs → Utf Symbols Scroll
3. Scroll all the way down in the preview
4. Open code/addons/docs/template/stories/docs2/UtfSymbolScroll.mdx in your editor and make
   a trivial change (add a space or letter), then save
5. Before fix: page jumps back to the top on hot reload
6. After fix: page stays at your scroll position after hot reload

Also verify normal navigation still resets scroll correctly:

• Click a different story in the sidebar → scroll resets to top
• Switch from story view to docs view → scroll resets to top

Video Demo

Before Fix

bug_replicate_1mp4.mp4

bug_replicate_2.mp4

After Fix

hot_reload_bug_fix.mp4

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook publish.yml --field pr=<PR_NUMBER>

Summary by CodeRabbit

• Documentation

  • Updated a docs story’s instruction text and reformatted its example markup for clearer layout and consistent styling.

• Bug Fixes

  • Improved docs preview scroll behavior so the page scroll is reset only when the displayed story or view mode changes, avoiding unnecessary scroll resets.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 318aeec5-daaa-4ece-bdbc-370f6f042b22

📥 Commits

Reviewing files that changed from the base of the PR and between 9400098 and de87198.

📒 Files selected for processing (1)

• code/addons/docs/template/stories/docs2/UtfSymbolScroll.mdx

✅ Files skipped from review due to trivial changes (1)

• code/addons/docs/template/stories/docs2/UtfSymbolScroll.mdx

---

📝 Walkthrough

Walkthrough

The PR adds a conditional scroll-position reset to the docs rendering flow: View.prepareForDocs now accepts { scrollReset?: boolean }. WebView defaults scrollReset to true and only resets document scroll when true. PreviewWithSelection passes story/view-change-driven scrollReset. One MDX story's formatting was adjusted.

Changes

Scroll Reset Control in Docs Preparation

Layer / File(s)	Summary
Scroll reset API contract and implementation code/core/src/preview-api/modules/preview-web/View.ts, code/core/src/preview-api/modules/preview-web/WebView.ts	View.prepareForDocs now accepts optional { scrollReset?: boolean }. WebView.prepareForDocs defaults scrollReset = true, applies main+docs layout and fullscreen, and only resets document.documentElement scroll when scrollReset is true.
Integration with preview selection logic code/core/src/preview-api/modules/preview-web/PreviewWithSelection.tsx	PreviewWithSelection computes scrollReset as `storyIdChanged
UTF Symbol Scroll test story update code/addons/docs/template/stories/docs2/UtfSymbolScroll.mdx	Instruction paragraph reflowed and the green scroll-test <div> reformatted to multi-line JSX with consistent style values; visual/semantic behavior unchanged.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@code/addons/docs/template/stories/docs2/UtfSymbolScroll.mdx`:
- Around line 9-10: Fix the typo in the manual test text in UtfSymbolScroll.mdx
by replacing "T hat" with "That" in the sentence following the link "Click on
[link](`#anchor-with-utf-symbols-абвг`)" so the instruction reads "That will jump
scroll to anchor after green block below." Ensure only the whitespace/typo is
corrected and no other text is altered.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: aeda7c6e-3e4a-49e4-9e2c-96a28f73a245

📥 Commits

Reviewing files that changed from the base of the PR and between c4f53de and 9400098.

📒 Files selected for processing (4)

• code/addons/docs/template/stories/docs2/UtfSymbolScroll.mdx
• code/core/src/preview-api/modules/preview-web/PreviewWithSelection.tsx
• code/core/src/preview-api/modules/preview-web/View.ts
• code/core/src/preview-api/modules/preview-web/WebView.ts

[valentinpalkovic]

Thank you so much for your contribution and your thorough proof-of-work videos! This is so helpful!

[storybook-app-bot]

Package Benchmarks

^{Commit: de87198, ran on 3 June 2026 at 07:12:11 UTC}

The following packages have significant changes to their size or dependencies:

storybook

	Before	After	Difference
Dependency count	72	72	0
Self size	20.41 MB	20.39 MB	🎉 -13 KB 🎉
Dependency size	36.11 MB	36.11 MB	0 B
Bundle Size Analyzer	Link	Link

@storybook/cli

	Before	After	Difference
Dependency count	203	203	0
Self size	908 KB	908 KB	🎉 -144 B 🎉
Dependency size	88.60 MB	88.58 MB	🎉 -13 KB 🎉
Bundle Size Analyzer	Link	Link

@storybook/codemod

	Before	After	Difference
Dependency count	196	196	0
Self size	32 KB	32 KB	0 B
Dependency size	87.08 MB	87.07 MB	🎉 -13 KB 🎉
Bundle Size Analyzer	Link	Link

create-storybook

	Before	After	Difference
Dependency count	73	73	0
Self size	1.08 MB	1.08 MB	0 B
Dependency size	56.52 MB	56.50 MB	🎉 -13 KB 🎉
Bundle Size Analyzer	node	node