# Router Client-side routing for shelving apps. Two pieces: | Component | Job | | --------------- | ---------------------------------------------------------------------------------------------- | | `` | One per app. Owns URL state, intercepts link clicks, listens for `popstate`. | | `` | Pure matcher. Reads URL from ``, matches `routes`, renders the matched element. | Plus `requireNavigation()` for imperative `forward()` / `redirect()` calls from anywhere in the tree. `` reads URL state from ``, so it works with no `` at all (SSR, static rendering, tests). `` is what publishes a *live* URL into `` on the client. ## Basic setup ```tsx ``` - Route keys are `AbsolutePath` strings starting with `/`. - Placeholders (`{id}`, `:id`, `[id]`, `${id}`, `{{id}}`) are passed to function/component routes as props (merged with URL `?query` params; placeholders win on conflict). - A string value (e.g. `"/users/123"`) is a redirect — visiting the key path navigates to the target. - `` itself accepts `PossibleMeta` props (`url`, `base`, etc.) to override the surrounding context. ## Route value types | Value | Behaviour | | --------------------- | ---------------------------------------------------------------------- | | `RouteComponent` | Rendered as `` with merged placeholder + query. | | `AbsolutePath` string | Redirects to that path (placeholders resolved against the source). | | `ReactElement` | Rendered as-is — use for layout wrapping or composing inner routers. | ## Placeholder syntax All forms produce the same matched value — pick whichever reads best: | Form | Single segment | Catchall (one+ segments, also matches empty) | | ----------------- | ---------------------- | -------------------------------------------- | | Anonymous | `*` (named `"0"`) | `**` / `***` / `****` (named `"0"`) | | Colon | `:name` | `:name*` / `:name**` | | Single brace | `{name}` | `{...name}` / `{name*}` / `{....name}` | | Square bracket | `[name]` | `[...name]` / `[name*]` | | Dollar brace | `${name}` | `${...name}` / `${name*}` | | Double brace | `{{name}}` | `{{...name}}` / `{{name*}}` | Modifier chars are tolerant: one-or-more stars and three-or-more dots are all equivalent. So `{path*}`, `{path**}`, `{...path}`, and `{....path}` all behave the same. Catchall placeholders allow empty values, so a trailing catchall matches the trailing-slash-absent variant too — `/files/{...path}` matches both `/files`, `/files/`, and `/files/a/b/c`. ## Layout wrapping Put layout JSX as the route value with another `` inside. ```tsx const SIDEBARRED_ROUTES = { "/users": , "/users/{id}": , "/settings": , }; , "/{...path}": ( ), }}/> ``` The outer router matches everything, wraps in ``, and hands off to the inner router. Since `` reads its URL from ``, the inner router sees the same URL. ## Section / microsite pattern A self-contained "section" of the app — its own URL prefix, its own routes — composes via a catchall + a function route value that hands the captured sub-path to a nested router. ```tsx , "/users/{...path}": ({ path = "/" }) => ( ), }}/> ``` The outer router captures everything under `/users` into the `path` placeholder, then the inner router treats `path` as its starting URL. The inner router's `"/"` matches the bare `/users`; `/{id}` matches `/users/123`. Pull that out into a dedicated component for readability: ```tsx const USER_ROUTES = { "/": UsersPage, "/{id}": UserPage, "/{id}/edit": UserEditPage, }; export function UserRouter({ path = "/" }: { path?: AbsolutePath }) { return ; } // then at the call site: , "/users/{...path}": ({ path }) => , "/blog/{...path}": ({ path }) => , }}/> ``` Each section module owns its routes and exposes one component. The top-level router stays a flat list of section prefixes. ## Stacking layouts and sections The two patterns compose. Wrap a bunch of routes in a layout, then route further inside it: ```tsx const SIDEBARRED_ROUTES = { "/": , "/users/{...path}": ({ path }) => , "/blog/{...path}": ({ path }) => , "/settings": , }; , // no sidebar "/{...path}": ( // everything else wrapped ), }}/> ``` `/login` skips the sidebar. Every other path goes through `` and then the inner router decides what to render — including handing off to section routers via the catchall pattern. ## Navigation Inside a component, get the navigation store for imperative URL changes: ```tsx const nav = requireNavigation(); nav.forward("/users/123"); // push history nav.redirect("/login"); // replace history ``` Same-origin anchor clicks are intercepted automatically and turned into `forward()` calls. Add a `download` attribute to opt out. ## `` Force a full remount of children whenever the URL changes: ```tsx ``` ## SSR / static rendering `` has no client requirements — it reads from `` and re-renders when context changes. For static rendering, set `url` and `root` on the outer wrapper and skip ``: ```tsx renderToString( ); ``` For client-side SPAs, wrap the same tree in `` for live URL updates. ## Base paths `root="https://example.com/app/"` is supported. The base path prefix is stripped from the URL before route matching via `matchURLPrefix`. URLs that fall outside the base render as `null` from the router.