mirror of
https://github.com/hanzoai/next.js.git
synced 2026-09-24 17:00:51 +00:00
Zack TannerandGitHub
0cf373a585
**What:** `layout-router` currently forces style recalculation on every navigation by manipulating the `scroll-behavior` CSS property on the `<html>` element. This would impact most navigations, even though most don't use smooth scrolling **Why:** To prevent smooth scrolling during router navigation (which can feel janky), Next.js temporarily resets `scroll-behavior` to `auto`, then restores the original value (#40642). While this solves the UX issue, it causes performance overhead for the vast majority of users who don't have smooth scrolling configured. **How:** This PR introduces an optimization that checks for a `data-scroll-behavior="smooth"` attribute before manipulating styles. Only users who explicitly opt into smooth scrolling will experience the style recalculation. - The existing behavior is preserved by default - Opt-in to the new behavior by setting `experimental.optimizeRouterScrolling: true` in Next.js config - When smooth-scroll is detected on the document, a development warning is logged to notify that the default behavior will be changing in an upcoming major.
63 lines
2.2 KiB
Plaintext
63 lines
2.2 KiB
Plaintext
---
|
|
title: 'Missing data-scroll-behavior Attribute for Smooth Scroll'
|
|
---
|
|
|
|
## Why This Warning Occurred
|
|
|
|
Your application has smooth scrolling enabled via CSS (`scroll-behavior: smooth`), but you haven't added the `data-scroll-behavior="smooth"` attribute to your `<html>` element.
|
|
|
|
Next.js automatically attempts to detect the smooth scrolling configuration to ensure that navigating back/forward through the router doesn't also trigger the smooth scrolling behavior, as this is often not desired.
|
|
|
|
In a future version of Next.js, this behavior will no longer be automatically detected, and you will need to add the `data-scroll-behavior` attribute to your `<html>` element to opt-in to having Next.js disable smooth scrolling during route transitions.
|
|
|
|
## Possible Ways to Fix It
|
|
|
|
Add `data-scroll-behavior="smooth"` to your `<html>` element to prepare for the upcoming optimization:
|
|
|
|
```html filename="app/layout.tsx"
|
|
export default function RootLayout({ children, }: { children: React.ReactNode })
|
|
{ return (
|
|
<html lang="en" data-scroll-behavior="smooth">
|
|
<body>
|
|
{children}
|
|
</body>
|
|
</html>
|
|
) }
|
|
```
|
|
|
|
Or if you're using the Pages Router:
|
|
|
|
```html filename="pages/_document.tsx"
|
|
import { Html, Head, Main, NextScript } from 'next/document' export default
|
|
function Document() { return (
|
|
<html lang="en" data-scroll-behavior="smooth">
|
|
<head />
|
|
<body>
|
|
<main />
|
|
<NextScript />
|
|
</body>
|
|
</html>
|
|
) }
|
|
```
|
|
|
|
## Why This Optimization Matters
|
|
|
|
Without the data attribute, Next.js must modify the `scroll-behavior` style on the `<html>` element on every navigation to ensure smooth scrolling isn't triggered. This can cause unnecessary style recalculation and impact performance.
|
|
|
|
With the data attribute, Next.js can instantly detect smooth scrolling configuration without triggering style recalculation, resulting in faster navigation and making this behavior opt-in.
|
|
|
|
## Enabling the Optimization Early
|
|
|
|
You can enable this optimization early by adding the experimental flag to your `next.config.js`:
|
|
|
|
```js filename="next.config.js"
|
|
/** @type {import('next').NextConfig} */
|
|
const nextConfig = {
|
|
experimental: {
|
|
optimizeRouterScrolling: true,
|
|
},
|
|
}
|
|
|
|
module.exports = nextConfig
|
|
```
|