The URL is the single source of truth for visible UI state. Filters, sort, current tab, expanded panel, open modal, pagination cursor — all of it lives in query params or the path.

The reason: a URL you can share is a feature. A URL you can bookmark is a feature. A URL the back button can restore to exactly the same view is a feature.

The rule

Anything a user can see right now should be reconstructable from the URL. If they paste the URL into a new tab, they land on the same view — same tab open, same filters applied, same row expanded.

What goes in the URL

State	Where	Example
Current page	path	`/projects/acme/issues`
Tab selection	query param	`?tab=closed`
Filters	query param (comma-separated)	`?status=open,blocked&assignee=me`
Sort	query param	`?sort=-updated_at`
Pagination cursor	query param	`?cursor=eyJpZCI6...`
Open panel / modal	query param	`?panel=settings` or `?modal=invite`
Search query	query param	`?q=auth+bug`

What does NOT go in the URL

Form draft state (use local storage).
Auth state (cookies / session).
Transient UI feedback (toast visibility).
Cursor position inside text fields.
Hover/focus state.

Back/forward must restore scroll

When the user navigates back, the scroll position restores to where they were — automatically for <a href> and history.pushState, broken if you intercept with e.preventDefault() and don't restore.

// Save scroll on navigation away
useEffect(() => {
  return () => sessionStorage.setItem(`scroll:${pathname}`, String(window.scrollY));
}, [pathname]);
 
// Restore on mount
useEffect(() => {
  const saved = sessionStorage.getItem(`scroll:${pathname}`);
  if (saved) window.scrollTo(0, parseInt(saved));
}, [pathname]);

Most SPA routers (Next.js, React Router) do this automatically — verify yours does. If you've broken it with a custom scroll lock, fix the scroll lock.

Deep-link every modal

A modal at ?modal=invite-team should be openable directly via that URL. If a user shares "look at this invite flow," they should be able to paste the URL and land on the open modal.

Don't put modals in component state when they could be in URL state. The cost is one query param; the gain is shareability.

When to apply

Every page-level state change. Filters, tabs, sort, search, modals, expanded rows. If you find yourself reaching for useState for something a user can see, ask if it should be in the URL instead.

Gotcha

URL state and component state can drift. Use a single source — read from the URL (via useSearchParams or equivalent), write through the router. Don't mirror URL state into local state — that's a bug surface.

Also: long URLs (more than ~2000 chars) break in some places. If your URL state is getting that big, compress it (base64-encoded JSON) or move some of it to a server-side state (with a short URL key).

Sources

Vercel Web Interface Guidelines — "URL as state," "Deep-link everything," "Scroll positions persist."
Related: states-are-the-work (each URL state is a real state to design), viewport-custom-design.