ルーター →このページを編集.md

スクロール復元

@lazarv/react-serverには、ウィンドウスクロール、ネストされたスクロールコンテナ、ハッシュナビゲーション、非同期コンテンツを処理する完全なスクロール復元システムが含まれています — フラッシュなしのページリロード復元、自動prefers-reduced-motionサポート、ルートごとのカスタマイズフックを備えています。

スクロール復元を有効にする最も簡単な方法は、設定ファイルを使用することです：

react-server.config.mjs
export default {
  scrollRestoration: true,
};

これにより、早期復元スクリプトが<head>に注入され（Reactのハイドレーション前に実行 — フラッシュなし）、デフォルト設定で<ScrollRestoration>コンポーネントが自動レンダリングされます。

オプションを渡すこともできます：

react-server.config.mjs
export default {
  scrollRestoration: {
    behavior: "smooth", // "auto" | "smooth" | "instant"
  },
};

より細かい制御が必要な場合は、設定オプションの代わりにクライアントコンポーネントでコンポーネントを直接レンダリングします：

"use client";

import { ScrollRestoration } from "@lazarv/react-server/navigation";

export default function App({ children }) {
  return (
    <>
      <ScrollRestoration behavior="smooth" />
      {children}
    </>
  );
}

<ScrollRestoration>をアプリのトップレベルに一度配置します。以下を処理します：

プロップ：

プロップ型デフォルト説明
behavior"auto" | "smooth" | "instant""auto"window.scrollTo()に渡されるスクロール動作。ユーザーがprefers-reduced-motionを有効にしている場合、自動的に"auto"（インスタントスクロール）にフォールバック

スクロール位置は、履歴エントリごとのユニークなスクロールキーをキーとしてsessionStorageに保存されます。各ナビゲーションで：

  1. 現在のスクロール位置が保存される（ウィンドウ + すべての登録済みコンテナ）
  2. フォワードナビゲーションの場合 — トップにスクロール（または#hashターゲット）
  3. 戻る/進むナビゲーションの場合 — sessionStorageから保存位置を復元

ページリフレッシュ時、<head>内の早期スクリプトがReactのハイドレーション前に実行され、保存位置を同期的に復元します — ほとんどのSPAスクロール復元ソリューションを悩ませる位置ずれのフラッシュを防ぎます。

非同期コンテンツ（Suspenseバウンダリ、Activityトランジション）の場合、コンポーネントはrequestAnimationFrameポーリングを使用してスクロール復元を再試行し、ページがターゲット位置に到達するのに十分な高さになるまで最大500msまで待ちます。

ストレージ管理： sessionStorageのクォータを超えた場合、最も古い約50%のスクロールエントリが自動的に削除されます。

useScrollContainerを使用して、ネストされたスクロール可能な要素（サイドバー、チャットパネル、データテーブル）をウィンドウスクロールと一緒に自動保存/復元に登録します：

"use client";

import { useRef } from "react";
import { useScrollContainer } from "@lazarv/react-server/navigation";

export function Sidebar() {
  const ref = useRef(null);
  useScrollContainer("sidebar", ref);

  return (
    <nav ref={ref} style={{ overflow: "auto", height: "100vh" }}>
      {/* サイドバーコンテンツ */}
    </nav>
  );
}

idはナビゲーションとページリロードにわたってユニークかつ安定している必要があります。ユーザーが別のページに移動して戻るボタンを押すと、ウィンドウスクロールとサイドバースクロールの両方が保存位置に復元されます。

復元が発生した時点でコンテナ要素がまだマウントされていない場合（例：Suspenseバウンダリ内）、ターゲット位置は遅延され、コンテナが登録されるとすぐに適用されます。

命令的APIも非Reactコンテキストで使用できます：

import {
  registerScrollContainer,
  unregisterScrollContainer,
} from "@lazarv/react-server/navigation";

// 登録
registerScrollContainer("chat-messages", element);

// クリーンアップ
unregisterScrollContainer("chat-messages");

useScrollPositionを使用して、ルートごとのスクロール動作をカスタマイズします。ハンドラはすべてのナビゲーションで呼び出され、スクロールをオーバーライドまたは抑制できます：

"use client";

import { useCallback } from "react";
import { useScrollPosition } from "@lazarv/react-server/navigation";

export default function ScrollConfig() {
  useScrollPosition(
    useCallback(({ to, from, savedPosition }) => {
      const toPath = to.split("?")[0];
      const fromPath = from?.split("?")[0];

      // モーダルルートではスクロールをスキップ
      if (toPath.startsWith("/modal")) return false;

      // ダッシュボードタブ切り替え時はスクロール位置を維持
      if (
        toPath.startsWith("/dashboard/") &&
        fromPath?.startsWith("/dashboard/")
      ) {
        return false;
      }

      // カスタム位置にスクロール
      if (toPath === "/gallery") return { x: 0, y: 200 };

      // デフォルト動作を使用（戻る/進むで復元、フォワードナビでトップ）
      return undefined;
    }, [])
  );

  return null;
}

ハンドラパラメータ：

パラメータ型説明
tostringナビゲーション先のURL（パス + 検索、例："/products?sort=price")
fromstring | nullナビゲーション元のURL、初期ページロード時はnull
savedPosition{ x: number, y: number } | nullsessionStorageからの保存位置（戻る/進む時）、フォワードナビではnull

戻り値：

戻り値効果
{ x, y }指定位置にスクロール
falseスクロールを完全にスキップ
undefined / nullデフォルト動作にフォールバック

最後に登録されたハンドラのみがアクティブです。コンポーネントがアンマウントされるとハンドラは自動的に登録解除されます。

URLに#hashが含まれる場合、スクロール復元はelement.scrollIntoView()を使用してターゲット要素に自動的にスクロールします。まずidで要素を検索し、次に[name="..."]にフォールバックします。ハッシュスクロールは他のすべてのスクロール動作（useScrollPositionハンドラを含む）よりも優先されます。

スクロール復元システムはprefers-reduced-motionメディアクエリを尊重します。ユーザーがモーションの低減を要求した場合、"smooth"動作は自動的に"auto"（インスタントスクロール）にダウングレードされます。これはウィンドウスクロールとコンテナスクロール復元の両方に適用されます。

すべてのスクロール復元エクスポートは@lazarv/react-server/navigationから利用できます。

エクスポート型説明
ScrollRestorationコンポーネント可視要素はレンダリングしない。スクロールの保存/復元ライフサイクルを管理。プロップ：{ behavior? }
useScrollPositionフックルートごとのスクロール動作ハンドラを登録。(params) => ScrollPosition | false | undefinedを受け付ける
useScrollContainerフックスクロール可能な要素を保存/復元に登録。(id: string, ref: RefObject<HTMLElement>)を受け付ける
registerScrollContainer関数命令的なコンテナ登録。(id: string, element: HTMLElement)を受け付ける
unregisterScrollContainer関数登録済みコンテナを削除。(id: string)を受け付ける

設定オプション：

react-server.config.mjs
export default {
  // デフォルトで有効化
  scrollRestoration: true,

  // または動作を設定
  scrollRestoration: {
    behavior: "smooth", // "auto" | "smooth" | "instant"
  },
};
← ルーター: 設定ルーター: リソース →