diff --git a/code/addons/docs/template/stories/docs2/UtfSymbolScroll.mdx b/code/addons/docs/template/stories/docs2/UtfSymbolScroll.mdx
index d8aa64b1bf1c..4c67a5aa7b02 100644
--- a/code/addons/docs/template/stories/docs2/UtfSymbolScroll.mdx
+++ b/code/addons/docs/template/stories/docs2/UtfSymbolScroll.mdx
@@ -6,9 +6,11 @@ import { Meta } from '@storybook/addon-docs/blocks';
> Instruction below works only in iframe.html. Unknown code in normal mode (with manager) removes hash from url.
-Click on [link](#anchor-with-utf-symbols-абвг). That will jump scroll to anchor after green block below. Then reload page and
-it should smooth-scroll to that anchor.
+Click on [link](#anchor-with-utf-symbols-абвг). That will jump scroll to anchor after green block below. Then reload page and
+it should smooth-scroll to that anchor.
-
Space for scroll test
+
+ Space for scroll test
+
-## Anchor with utf symbols (абвг)
\ No newline at end of file
+## Anchor with utf symbols (абвг)
diff --git a/code/core/src/preview-api/modules/preview-web/PreviewWithSelection.tsx b/code/core/src/preview-api/modules/preview-web/PreviewWithSelection.tsx
index b37d5ed11939..9ccc49101e63 100644
--- a/code/core/src/preview-api/modules/preview-web/PreviewWithSelection.tsx
+++ b/code/core/src/preview-api/modules/preview-web/PreviewWithSelection.tsx
@@ -458,7 +458,7 @@ export class PreviewWithSelection extends Preview {
// Get ready to render a story, returning the element to render to
prepareForStory(story: PreparedStory): TStorybookRoot;
- prepareForDocs(): TStorybookRoot;
+ prepareForDocs(options?: { scrollReset?: boolean }): TStorybookRoot;
showErrorDisplay(err: { message?: string; stack?: string }): void;
diff --git a/code/core/src/preview-api/modules/preview-web/WebView.ts b/code/core/src/preview-api/modules/preview-web/WebView.ts
index 86e857907868..51e15fdb1102 100644
--- a/code/core/src/preview-api/modules/preview-web/WebView.ts
+++ b/code/core/src/preview-api/modules/preview-web/WebView.ts
@@ -81,13 +81,19 @@ export class WebView implements View {
return document.getElementById('storybook-root')!;
}
- prepareForDocs() {
+ prepareForDocs({ scrollReset = true }: { scrollReset?: boolean } = {}) {
this.showMain();
this.showDocs();
this.applyLayout('fullscreen');
- document.documentElement.scrollTop = 0;
- document.documentElement.scrollLeft = 0;
+ // Only reset scroll when navigating to a new docs page, not on HMR re-renders.
+ // Without this guard, hot-reloading a story file while scrolled down on a docs page
+ // causes the page to jump back to the top.
+
+ if (scrollReset) {
+ document.documentElement.scrollTop = 0;
+ document.documentElement.scrollLeft = 0;
+ }
return this.docsRoot();
}