Scroll behavior control in NextJS - Deep Dive

Overview - Scroll behavior control

What is it?

Scroll behavior control in Next.js means managing how the page moves up or down when users navigate between pages or interact with the site. It lets you decide if the page should jump instantly, smoothly glide, or stay in place when changing views. This helps create a better experience by guiding the user's eyes naturally. Without it, navigation can feel jarring or confusing.

Why it matters

Without scroll behavior control, users might lose their place on a page or feel disoriented when moving around a website. For example, clicking a link might suddenly jump to the top, making users lose context. Controlling scroll behavior makes navigation feel smooth and intentional, improving usability and keeping users engaged.

Where it fits

Before learning scroll behavior control, you should understand basic Next.js routing and React component structure. After mastering scroll control, you can explore advanced user experience techniques like animations, lazy loading, and state management tied to scroll position.

Mental Model

Core Idea

Scroll behavior control is about deciding how and when the page moves vertically during navigation to create smooth, predictable user experiences.

Think of it like...

It's like guiding someone through a photo album: you can flip pages quickly, slowly, or pause to focus on a picture, making the journey comfortable and clear.

┌─────────────────────────────┐
│ User clicks a link or event │
└─────────────┬───────────────┘
              │
      ┌───────▼────────┐
      │ Scroll Behavior │
      │   Decision     │
      └───────┬────────┘
              │
  ┌───────────▼───────────┐
  │ Instant jump to target │
  ├───────────────────────┤
  │ Smooth scroll to target│
  ├───────────────────────┤
  │ No scroll (stay put)   │
  └───────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding default scroll behavior

Concept: Learn how Next.js handles scrolling by default when navigating between pages.

By default, Next.js scrolls to the top of the page when you navigate to a new route. This means the user always starts at the top of the new page automatically. This behavior is built-in and requires no extra code.

Result

When you click a link to a new page, the browser jumps instantly to the top of that page.

Knowing the default helps you understand why sometimes users lose their scroll position and why you might want to customize this behavior.

2

Foundation

Using the Link component for navigation

Concept: Learn how Next.js's Link component triggers navigation and affects scroll behavior.

Next.js provides a Link component to navigate between pages without full reloads. When you use Link, Next.js handles the route change and scrolls to the top by default. You can customize this behavior by adding props or handling events.

Result

Clicking a Link changes the page and scrolls to the top automatically.

Understanding Link is key because scroll behavior control often ties into how navigation happens.

3

Intermediate

Controlling scroll with router events

🤔Before reading on: do you think you can stop scrolling by default using router events? Commit to yes or no.

Concept: Next.js exposes router events that let you run code during navigation, allowing you to control scroll behavior manually.

You can listen to router events like 'routeChangeComplete' to run code after navigation finishes. For example, you can scroll to a specific position or prevent scrolling by overriding default behavior. This requires using the useRouter hook and window.scrollTo or similar methods.

Result

You can customize where the page scrolls after navigation, such as staying in place or scrolling smoothly to a section.

Knowing router events unlocks precise control over scroll behavior beyond defaults.

4

Intermediate

Using scrollRestoration for back/forward buttons

🤔Before reading on: does the browser always restore scroll position automatically on back navigation in Next.js? Commit to yes or no.

Concept: The browser has a scrollRestoration API that controls if scroll position is saved and restored when using back/forward buttons. Next.js can use this to improve user experience.

By default, Next.js disables scrollRestoration to avoid conflicts. You can enable it manually in a useEffect hook to let the browser remember scroll positions when users navigate back or forward, making navigation feel natural.

Result

When users click back, the page scrolls to where they left off instead of jumping to the top.

Understanding scrollRestoration helps you fix confusing scroll jumps during back/forward navigation.

5

Intermediate

Implementing smooth scroll behavior

🤔Before reading on: do you think smooth scrolling requires complex libraries or can be done with simple browser APIs? Commit to your answer.

Concept: Modern browsers support smooth scrolling natively, which you can trigger with simple JavaScript or CSS to improve scroll transitions.

You can call window.scrollTo with behavior: 'smooth' to glide the page to a position instead of jumping. Alternatively, CSS property scroll-behavior: smooth can make all scrolls smooth automatically. This creates a nicer visual effect during navigation or user actions.

Result

Page scrolls smoothly to the target position instead of jumping instantly.

Knowing native smooth scroll APIs lets you enhance UX without extra dependencies.

6

Advanced

Custom scroll restoration with saved positions

🤔Before reading on: do you think you can save scroll positions manually to restore them later? Commit to yes or no.

Concept: You can build your own scroll restoration system by saving scroll positions in memory or storage and restoring them on navigation, giving full control over scroll state.

By listening to router events, you save the current scroll position before navigating away. When returning, you read the saved position and scroll there manually. This is useful for complex apps where default restoration is insufficient, like dynamic content or infinite scroll pages.

Result

Users return to exactly where they left off, even across complex navigation flows.

Understanding manual scroll restoration empowers you to build seamless experiences in complex apps.

7

Expert

Handling scroll with dynamic content and hydration

🤔Before reading on: do you think scroll position is always reliable immediately after navigation in Next.js? Commit to yes or no.

Concept: In Next.js, pages often load content dynamically or hydrate React components after navigation, which can change page height and affect scroll position accuracy.

If you scroll immediately after navigation, the page might not have fully loaded content, causing scroll jumps or wrong positions. Experts delay scroll restoration until content is ready, using techniques like waiting for images to load or React hydration to complete. This ensures scroll position is accurate and stable.

Result

Scroll position matches user expectation without sudden jumps or flickers after navigation.

Knowing how dynamic content affects scroll lets you avoid subtle bugs that frustrate users in real apps.

Under the Hood

Next.js uses the browser's History API to change routes without full reloads. When navigation happens, Next.js triggers events and updates the URL. By default, it scrolls the window to the top. The browser also has a scrollRestoration property that can save and restore scroll positions on back/forward navigation. Developers can hook into router events to override or enhance this behavior by calling window.scrollTo or manipulating scroll containers.

Why designed this way?

Next.js aims for fast, seamless navigation like a single-page app but with server-side rendering benefits. Default scroll to top matches user expectations for new pages. However, scroll restoration is disabled by default to avoid conflicts with dynamic content loading and React hydration. This design balances simplicity for most cases with flexibility for advanced control.

┌───────────────┐
│ User triggers │
│ navigation    │
└───────┬───────┘
        │
┌───────▼─────────────┐
│ Next.js Router      │
│ updates URL & state │
└───────┬─────────────┘
        │
┌───────▼─────────────┐
│ Router Events fire  │
│ (routeChangeStart,  │
│  routeChangeComplete)│
└───────┬─────────────┘
        │
┌───────▼─────────────┐
│ Scroll Behavior Code │
│ (default or custom)  │
└───────┬─────────────┘
        │
┌───────▼─────────────┐
│ Browser scroll moves │
│ window or container  │
└─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does Next.js automatically restore scroll position on back navigation? Commit to yes or no.

Common Belief: Next.js always restores scroll position automatically when using back or forward buttons.

Reality: By default, Next.js disables browser scroll restoration, so scroll position is not restored unless you enable it manually.

Why it matters: Assuming automatic restoration leads to confusing user experiences with unexpected scroll jumps on back navigation.

Quick: Is smooth scrolling only possible with external libraries? Commit to yes or no.

Common Belief: You need third-party libraries to implement smooth scrolling in Next.js.

Reality: Modern browsers support smooth scrolling natively via CSS or JavaScript APIs without extra libraries.

Why it matters: Believing this causes unnecessary complexity and larger bundle sizes.

Quick: Does scrolling immediately after navigation always work correctly? Commit to yes or no.

Common Belief: You can scroll to any position right after route change and it will be accurate.

Reality: Dynamic content loading and React hydration can change page height after navigation, making immediate scroll unreliable.

Why it matters: Ignoring this causes flickering scroll jumps and poor user experience.

Quick: Does disabling scroll on navigation mean the page never moves? Commit to yes or no.

Common Belief: If you disable scroll on navigation, the page will never scroll even when needed.

Reality: You can selectively control scroll behavior to keep position or scroll to specific places as needed.

Why it matters: Misunderstanding this limits creative scroll control and harms UX.

Expert Zone

1

Scroll restoration must consider asynchronous data loading to avoid jumping scroll positions after content changes.

2

Using router events for scroll control requires careful cleanup to prevent memory leaks or conflicting scroll commands.

3

Custom scroll containers (not window) need manual scroll management since browser APIs default to window scrolling.

When NOT to use

Avoid custom scroll control when your app has simple static pages where default behavior suffices. For very complex scroll interactions, consider dedicated libraries like react-scroll or full-page scroll frameworks instead of manual control.

Production Patterns

In production, developers combine router event listeners with saved scroll positions in session storage to restore user context. Smooth scroll is often enabled globally via CSS for consistent feel. Complex apps delay scroll restoration until data fetching completes to avoid jumps.

Connections

Single Page Application (SPA) Routing

Scroll behavior control builds on SPA routing concepts by managing page position during client-side navigation.

Understanding SPA routing helps grasp why scroll control is needed to mimic traditional page loads smoothly.

User Experience Design

Scroll behavior control directly impacts UX by guiding user attention and reducing confusion during navigation.

Knowing UX principles clarifies why smooth and predictable scrolling improves user satisfaction.

Memory Management in Operating Systems

Like saving and restoring scroll positions, OS memory management saves and restores process states to maintain continuity.

This cross-domain link shows how saving state for smooth transitions is a universal pattern in computing.

Common Pitfalls

#1 Page jumps to top immediately after navigation even when you want to keep scroll position.

Wrong approach:

router.events.on('routeChangeComplete', () => {
// No scroll control here
});

Correct approach:

router.events.on('routeChangeComplete', () => {
window.scrollTo({ top: savedPosition, behavior: 'auto' });
});

Root cause:

Not handling scroll manually after navigation leaves default scroll to top behavior active.

#2 Scroll restoration breaks because scrollRestoration is not enabled.

Wrong approach:

useEffect(() => {
// No scrollRestoration setup
}, []);

Correct approach:

useEffect(() => {
if ('scrollRestoration' in window.history) {
window.history.scrollRestoration = 'auto';
}
}, []);

Root cause:

Assuming browser handles scroll restoration without enabling it in Next.js.

#3 Smooth scroll causes flicker because it runs before content loads.

Wrong approach:

router.events.on('routeChangeComplete', () => {
window.scrollTo({ top: 0, behavior: 'smooth' });
});

Correct approach:

router.events.on('routeChangeComplete', () => {
setTimeout(() => {
window.scrollTo({ top: 0, behavior: 'smooth' });
}, 100); // wait for content
});

Root cause:

Triggering scroll before dynamic content finishes loading causes visual jumps.

Key Takeaways

Next.js scroll behavior control lets you manage how the page moves during navigation to improve user experience.

By default, Next.js scrolls to the top on new pages and disables browser scroll restoration on back/forward navigation.

You can use router events and browser APIs to customize scroll position, enable smooth scrolling, and restore scroll state manually.

Handling dynamic content loading and hydration timing is crucial to avoid scroll position bugs.

Expert scroll control balances default simplicity with advanced manual techniques for seamless, intuitive navigation.