Update router documentation for new URL API

[masenf]

Type of change

• This change requires a documentation update

Description

This PR updates the documentation to reflect changes in the router API. The changes document the transition from the deprecated router.page namespace to the new router.url API and router.route_id attribute.

Key documentation updates:

1. Updated router attributes examples in docs/utility_methods/router_attributes.md:

   • Replaced deprecated router.page.* attributes with new router.url.* components
   • Added examples for router.url.scheme, router.url.netloc, router.url.origin, router.url.query, router.url.query_parameters, and router.url.fragment
   • Added router.route_id example

2. Added comprehensive URL Attributes section documenting:

   • The structure and purpose of router.url as a parsed URL object
   • All available URL component attributes with descriptions
   • A detailed example table showing URL parsing for a concrete request
   • Best practices for reading query parameters using query_parameters
   • Reference to dynamic route handling

3. Added migration guide from deprecated router.page to new API:

   • Mapping table showing old attributes and their replacements
   • Notes explaining behavioral differences (e.g., query_parameters is now a frozen mapping)

4. Updated overview documentation in docs/pages/overview.md:

   • Changed code examples to use router.route_id instead of router.page.path
   • Changed code examples to use router.url.path instead of router.page.raw_path
   • Updated explanations to reference the new API
   • Simplified full URL access to use router.url directly

Fixes #5664

Test Plan

N/A - Documentation only changes

https://claude.ai/code/session_01GTk6Ni7kyfd8VQKtq7JAXh

[greptile-apps]

Greptile Summary

This PR migrates the router documentation from the deprecated router.page.* API to the new router.url (a str-subclass parsed URL object) and router.route_id, and backs the change with a new Var implementation (ReflexURLCastedVar) that serializes ReflexURL as a component dict so the frontend can access individual URL fields. The code changes are well-tested and the eager serializer bypass for the str-subclass is correctly handled and documented.

Confidence Score: 5/5

Safe to merge; only finding is a minor documentation gap in the migration guide.

All remaining findings are P2 documentation suggestions. The implementation is solid, the serializer bypass is correctly handled, VarData propagation is explicitly tested, and both test fixture files are consistently updated.

docs/utility_methods/router_attributes.md — migration note for raw_path omits fragment.

Important Files Changed

Filename	Overview
reflex/istate/data.py	Adds ReflexURLVar/ReflexURLCastedVar Var wrappers and an eager _serialize_reflex_url serializer; the bypass of the generic serializer for the str-subclass ReflexURL is correctly handled and well-commented.
tests/units/istate/test_data.py	New test file covering URL parsing, serialization round-trip through json_dumps, Var type registration, VarData propagation, JS expression rendering, and query_parameters ObjectVar typing — comprehensive coverage.
docs/utility_methods/router_attributes.md	Replaces deprecated router.page.* examples with router.url.* and adds URL Attributes + migration guide sections; migration note for raw_path omits the fragment component.
docs/pages/overview.md	Updates code examples to use router.route_id and router.url.path/router.url in place of deprecated router.page.* attributes — accurate and well-worded.
tests/units/test_state.py	Updates formatted_router fixture to reflect url now serializing as a component dict instead of a plain string.
tests/units/utils/test_format.py	Same formatted_router fixture update as test_state.py — consistent and correct.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["Frontend URL in browser\nhttps://example.com:3000/posts/123?tab=comments#top"] -->|"WebSocket router payload"| B["RouterData.from_router_data()"]
    B --> C["ReflexURL (str subclass)\nstores full URL + parsed attrs"]
    C -->|"_serialize_reflex_url() called eagerly\n(bypasses json.dumps str-subclass shortcut)"| D["Serialized dict\n{href, scheme, netloc, origin,\npath, query, query_parameters, fragment}"]
    D -->|"State sync to frontend"| E["JS state object\nreflex_state.router.url"]
    E -->|"ReflexURLCastedVar._cached_var_name"| F["router.url → url?.['href']\n(full URL string)"]
    E -->|"_component('scheme').to(str)"| G["router.url.scheme → url?.['scheme']"]
    E -->|"_component('query_parameters')\n.to(ObjectVar, Mapping[str,str])"| H["router.url.query_parameters\n→ url?.['query_parameters']"]

Loading

_{Reviews (2): Last reviewed commit: "fix(state): explicitly serialize ReflexU..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 17 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing claude/document-router-url-87UPj (18b5578) with main (76ff38c)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[masenf]

@greptile-apps re-review