PixelPilot: Instructions file for GitHub Copilot

Scroll Restoration Skill

Preserve user scroll position across page navigations for better UX.

---

CORE PRINCIPLE

Rule: When a user navigates away and returns, restore their scroll position. For fresh navigations, scroll to top. Always respect prefers-reduced-motion.

---

REACT ROUTER (v6+)

Using ScrollRestoration Component

// app/root.tsx or App.tsx
import { ScrollRestoration } from 'react-router-dom';

export default function App() {
  return (
    <>
      <Outlet />
      <ScrollRestoration
        getKey={(location, matches) => {
          // Use pathname as key (default behavior)
          return location.pathname;
          
          // Or use location key for history-based restoration
          // return location.key;
        }}
      />
    </>
  );
}

Custom Scroll Restoration Hook

// hooks/useScrollRestoration.ts
import { useEffect, useLayoutEffect, useRef } from 'react';
import { useLocation } from 'react-router-dom';

const scrollPositions = new Map<string, number>();

export function useScrollRestoration() {
  const location = useLocation();
  const prevPathRef = useRef<string | null>(null);
  const prefersReducedMotion = useRef(
    typeof window !== 'undefined' &&
    window.matchMedia('(prefers-reduced-motion: reduce)').matches
  );

  // Save scroll position before navigation
  useEffect(() => {
    const handleBeforeUnload = () => {
      scrollPositions.set(location.pathname, window.scrollY);
    };

    // Save on route change
    return () => {
      scrollPositions.set(location.pathname, window.scrollY);
    };
  }, [location.pathname]);

  // Restore scroll position after navigation
  useLayoutEffect(() => {
    const savedPosition = scrollPositions.get(location.pathname);
    
    // Scroll behavior based on motion preference
    const scrollOptions: ScrollToOptions = {
      top: savedPosition ?? 0,
      left: 0,
      behavior: prefersReducedMotion.current ? 'instant' : 'instant' // Always instant for restoration
    };

    // Use requestAnimationFrame to ensure DOM is ready
    requestAnimationFrame(() => {
      window.scrollTo(scrollOptions);
    });

    prevPathRef.current = location.pathname;
  }, [location.pathname]);
}

// Usage in App.tsx
function App() {
  useScrollRestoration();
  return <Outlet />;
}