---
title: Scroll Restoration Behavior
slug: experience/scroll-restoration-behavior
docTags: 
createdAt: 2026-02-25T11:35:59.035Z
---

## Overview

Our application automatically restores your previous scroll position when navigating between pages. However, due to lazy loading of content, this restoration may not always appear smooth or accurate.

## Current Behavior

### Content at the Bottom Not Loaded

**What happens:**

- When you navigate back to a page where you previously scrolled down
- The content at the bottom may not be loaded yet due to lazy loading
- The app will retry scrolling multiple times to reach your previous position
- You'll see the page "jump" several times as content loads and the page height increases

**Why this happens:**

- Your previous scroll position was further down the page than what's currently visible
- Lazy-loaded content needs time to load and expand the page height
- The app keeps trying to scroll to the exact position until the content is available

### Content at the Top Not Loaded

**What happens:**

- Your scroll position is restored immediately when returning to a page
- Additional content loads at the top of the page afterward
- This new content pushes existing content downward
- You end up at the wrong scroll position (too far down)

## Controlling Scroll Restoration

You can now control this behavior using the `LazyScrollRestoration` feature flag in your experience configuration.

### Configuration

Add this to your `experience.config.json`:

```json
{
  "purple": {
    "features": {
      "lazyScrollRestoration": false
    }
  }
}
```

### Behavior Options

**When disabled  (**`false`**):**

- ✅ No scroll jumps - smooth experience
- ⚠️ Restored position may not be exact
- Best for: Users who prefer smooth scrolling over precise positioning

**When enabled (**`true`** or not set):**

- ⚠️ May see scroll jumps as content loads
- ✅ Guarantees you end up at the correct final position
- Best for: Users who need precise scroll position restoration

### Recommendation

Choose based on your content and user experience priorities:

- **Enable** if you have heavy lazy loading and prefer smooth navigation
- **Keep disabled** if precise scroll positioning is critical for your users