Keep page state across navigation

You'll build a page with a notes field, a packing checklist and a list of hikes. Open a hike, press Back and the page comes back the way you left it: the notes still typed, the items still ticked and the list still scrolled. It takes one option on the navigator you already have.

Before you start

Install from crates.io. You need no Node and no package manager.

cargo install snapfire_compiler
cargo install snapfire_fsr_cli
fsr --version

Every command and screenshot on this page was captured with fsr 0.x.

A page worth coming back to#

$ fsr new trail --with react

The hikes, in app/src/hikes.ts:

app/src/hikes.ts

export type Hike = { slug: string; name: string; miles: number; climb: number };

export const HIKES: Hike[] = [
  { slug: "mist-falls", name: "Mist Falls", miles: 8, climb: 800 },
  { slug: "half-dome", name: "Half Dome", miles: 16, climb: 4800 },
  { slug: "clouds-rest", name: "Clouds Rest", miles: 14, climb: 3100 },
  { slug: "sentinel-dome", name: "Sentinel Dome", miles: 2, climb: 400 },
  { slug: "four-mile", name: "Four Mile Trail", miles: 9, climb: 3200 },
  { slug: "cathedral-lakes", name: "Cathedral Lakes", miles: 7, climb: 1000 },
  { slug: "north-dome", name: "North Dome", miles: 9, climb: 1500 },
  { slug: "taft-point", name: "Taft Point", miles: 2, climb: 250 },
];

A packing checklist, as an ordinary React component with its own state:

app/src/ui/Packing.tsx

import { useState } from "react";

const ITEMS = ["Water", "Map", "Headlamp", "Rain shell", "Snacks"];

export function Packing() {
  const [packed, setPacked] = useState<string[]>([]);
  const toggle = (item: string) => setPacked(packed.includes(item) ? packed.filter((i) => i !== item) : [...packed, item]);
  return (
    <fieldset className="packing">
      <legend>
        Packed {packed.length} of {ITEMS.length}
      </legend>
      {ITEMS.map((item) => (
        <button key={item} className={packed.includes(item) ? "packed" : ""} onClick={() => toggle(item)}>
          {item}
        </button>
      ))}
    </fieldset>
  );
}

The index has a plain textarea, the checklist as an island and a link to each hike:

app/routes/page.loader.ts

import type { Ctx } from "@snapfire/fsr";
import { HIKES } from "@src/hikes";

export async function load(_ctx: Ctx<"/">) {
  return { hikes: HIKES };
}

app/routes/page.tsx

import type { RootProps } from "@generated/client";
import { Island, Link } from "@snapfire/fsr-client/react";
import { Packing } from "@src/ui/Packing";

export default function Index({ hikes }: RootProps) {
  return (
    <section>
      <h1>Plan a hike</h1>
      <label className="notes">
        Notes
        <textarea name="notes" rows={3} />
      </label>
      <Island when="load">
        <Packing />
      </Island>
      <ul className="hikes">
        {hikes.map((h) => (
          <li key={h.slug}>
            <Link href={`/hike/${h.slug}`}>{h.name}</Link>
            <span>
              {h.miles} mi, {h.climb} ft
            </span>
          </li>
        ))}
      </ul>
    </section>
  );
}

Each hike gets a short page of its own:

app/routes/hike/[slug]/page.loader.ts

import type { Ctx } from "@snapfire/fsr";
import { fail } from "@snapfire/fsr";
import { HIKES } from "@src/hikes";

export async function load({ params }: Ctx<"/hike/{slug}">) {
  const hike = HIKES.find((h) => h.slug === params.slug);
  if (!hike) fail("not_found", `there is no hike ${params.slug}`);
  return { hike };
}

app/routes/hike/[slug]/page.tsx

import type { HikeSlugProps } from "@generated/client";
import { Link } from "@snapfire/fsr-client/react";

export default function HikePage({ hike }: HikeSlugProps) {
  return (
    <article>
      <Link href="/">All hikes</Link>
      <h1>{hike.name}</h1>
      <p>
        {hike.miles} miles round trip with {hike.climb} feet of climbing.
      </p>
    </article>
  );
}

Some layout, at the end of app/styles/app.css. The tall rows make the list long enough to scroll:

app/styles/app.css

.notes {
  display: grid;
  gap: 6px;
  margin-bottom: 24px;
}

.packing {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
  margin-bottom: 24px;
}

.packing .packed {
  text-decoration: line-through;
}

.hikes li {
  display: flex;
  justify-content: space-between;
  padding: 48px 0;
}

Without activity#

$ fsr dev trail/app

Open http://127.0.0.1:3000. Type something into Notes, tick Water and Map, scroll down and click Taft Point. Now press Back. The page is there again, but Notes is empty, nothing is ticked and the window is at the top. The navigator rendered the index again from its payload, so whatever the visitor did to the old one is gone.

Turn activity on#

Give the navigator one option in app/src/main.ts:

app/src/main.ts

import { boot, enableNavigation } from "@snapfire/fsr-client";
import { registerIslands } from "@generated/islands.js";

registerIslands();

boot();
enableNavigation({ activity: true });

Do the same thing again: type a note, tick two items, scroll down, open a hike and press Back. The notes are still typed, Packed reads 2 of 5 and the list is scrolled where you left it. Clicking All hikes instead of Back brings back the notes and the ticks too. A link scrolls to the top as any link does, while Back returns to where you were.

LiveThe trail planner from this tutorial, on a site with activity on

Notes

Packed 0 of 5

Mist Falls8 mi, 800 ft
Half Dome16 mi, 4800 ft
Clouds Rest14 mi, 3100 ft
Taft Point2 mi, 250 ft

This site's navigator runs with activity: true. Type a note, tick two items, open a hike and press Back: this page comes back as you left it.

What happened#

With activity: true, the navigator stops throwing away the page a visitor leaves. It takes the page's DOM out of the document and keeps it, up to ten pages, the one left longest ago dropped first. When a navigation lands on a page it is keeping, it puts that DOM back and patches it to the new payload, leaving every field's value alone. The textarea keeps its text because it is the same element. A video keeps its position and a custom element keeps whatever it holds for the same reason.

The checklist is a React island. React 19.2 and later can pause a tree without unmounting it. The navigator renders the island under React's <Activity> and switches it to hidden while the page is kept, so its useState survives and its effects stop until the page comes back. A Vue island, or a React island on an earlier React, cannot be paused that way. It is unmounted when the page is kept and mounts afresh when the page comes back.

An action that revalidates, a refresh or a new session drops every kept page, so a visitor never comes back to a page that shows data from before they changed it.

Try it#

Opt one link out. Change the hike links on the index to:

<Link href={`/hike/${h.slug}`} data-sf-activity="none">{h.name}</Link>

Open a hike from the list and press Back: the index renders fresh, as it did without activity. The attribute works the other way too. Leave enableNavigation() with no options and put data-sf-activity on just the links whose page is worth keeping. activityLimit changes how many pages are kept:

enableNavigation({ activity: true, activityLimit: 3 });