AddThisFeature

URL State Hook

Put shareable view state in the URL through one consistent, validated accessor.

moderate Developer Experience

What it adds

A single typed accessor for the filters, tabs, panel positions, and selections the app keeps in its query string.

What your agent is told to do

5
  1. 1

    Identify every screen where a colleague pasting the current URL should see the same thing — filtered lists, selected tabs, opened detail panels, date ranges, search terms — and route all of them through one accessor instead of the several ad hoc parsers already in the codebase.

  2. 2

    Declare a type and a default for each parameter, and parse defensively: an unknown sort key, a negative page, or a date that does not exist must fall back to the default rather than reaching the query layer.

  3. 3

    Read and write parameters non-destructively, merging into what is already in the URL so unrelated parameters set by another component, a campaign tag, or a deep link survive untouched.

  4. 4

    Decide per parameter whether a change pushes a history entry or replaces the current one, and write the decision down. A filter the user deliberately chose deserves a back button; a search box updating as they type does not.

  5. 5

    Which of the user's arrangements live in the URL and which live in their account is settled by Persistent View Preferences. Anything worth sharing in a link belongs here; anything personal and durable, such as column widths, belongs there. Do not store the same choice in both.

Edge cases it handles

7
  • Malformed or hostile values arrive constantly from stale bookmarks, truncated chat links, and hand-edited URLs. Every parameter must be validated and coerced to a safe default rather than passed through to a fetch or a query.
  • Writing a parameter must preserve the ones this component knows nothing about — referral tags, an unrelated open panel, a scroll anchor — because clobbering them turns a shared link into a broken one.
  • Pushing a history entry for every keystroke buries the previous page under fifty back presses, while replacing a deliberate filter change makes the back button skip it. The choice has to be per parameter and intentional.
  • On a server-rendered page the URL is known before the browser is, so the first client render must derive its state from the same parsed URL rather than from a default that then swaps — that swap is a hydration mismatch and a visible flash.
  • Two components writing different parameters in the same tick must not overwrite each other; reads must be against the live URL rather than a captured value.
  • URLs have practical length limits in browsers, logs, and chat clients, so a long multi-select filter needs a compact encoding or a saved-view identifier instead of a hundred repeated keys.
  • Parameters that carry a record identifier the current user may no longer access must degrade to that view's own empty or forbidden state, not a blank screen.

Definition of done

9
  • All shareable view state is read and written through one accessor with declared types and defaults.
  • Invalid, unknown, or out-of-range values fall back to defaults and never reach a query.
  • Writing one parameter leaves every other parameter in the URL intact.
  • Each parameter documents whether it pushes or replaces a history entry, and behaves accordingly.
  • A pasted URL reproduces the same view for another permitted user.
  • The first client render matches the server render for every URL-derived value.
  • URL state and stored view preferences do not both own the same choice.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.