# Route

```ts
import { Route } from 'cx/widgets';
```



Route is a container that renders its children only when the current URL matches the specified pattern.

## Example

```tsx
import { createModel } from "cx/data";
import { Controller } from "cx/ui";
import { Route, Button } from "cx/widgets";

interface PageModel {
  url: string;
}

const m = createModel<PageModel>();

class PageController extends Controller<PageModel> {
  onInit() {
    this.store.init(m.url, "~/home");
  }
}

export default (
  <div controller={PageController} class="flex flex-col gap-4">
    <nav class="flex gap-2">
      <Button onClick={(e, { store }) => store.set(m.url, "~/home")}>
        Home
      </Button>
      <Button onClick={(e, { store }) => store.set(m.url, "~/about")}>
        About
      </Button>
      <Button onClick={(e, { store }) => store.set(m.url, "~/contact")}>
        Contact
      </Button>
    </nav>
    <div class="p-4 bg-muted rounded">
      <Route route="~/home" url={m.url}>
        <h2 class="font-semibold">Home</h2>
        <p class="text-sm text-muted-foreground">Welcome to the home page.</p>
      </Route>
      <Route route="~/about" url={m.url}>
        <h2 class="font-semibold">About</h2>
        <p class="text-sm text-muted-foreground">Learn more about us.</p>
      </Route>
      <Route route="~/contact" url={m.url}>
        <h2 class="font-semibold">Contact</h2>
        <p class="text-sm text-muted-foreground">Get in touch with us.</p>
      </Route>
    </div>
    <div class="text-xs text-muted-foreground">
      Current URL: <code text={m.url} />
    </div>
  </div>
);

```

## Route Patterns

Routes support parameters, splats, and optional parts using [route-parser](https://github.com/rcs/route-parser#what-can-i-use-in-my-routes) syntax:

| Pattern         | Description          | Example Match                    |
| --------------- | -------------------- | -------------------------------- |
| `~/users`       | Exact match          | `/users`                         |
| `~/users/:id`   | Named parameter      | `/users/123` → `id: "123"`       |
| `~/files/*path` | Splat (rest of path) | `/files/a/b/c` → `path: "a/b/c"` |
| `~/users(/:id)` | Optional parameter   | `/users` or `/users/123`         |

## Prefix Matching

Use `prefix` to match routes that start with a pattern:

```tsx
<Route route="~/admin" url={m.url} prefix>
  {/* Matches ~/admin, ~/admin/users, ~/admin/settings, etc. */}
  <AdminLayout />
</Route>
```

## Nested Routes

Use `+/` to define routes relative to the parent:

```tsx
<Route route="~/admin" url={m.url} prefix>
  <Route route="+/users" url={m.url}>
    <UsersPage />
  </Route>
  <Route route="+/settings" url={m.url}>
    <SettingsPage />
  </Route>
</Route>
```

## Configuration

| Property         | Type           | Description                                                                                                                                |
| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `route` / `path` | `string`       | Target route, e.g. `~/user/:userId`. Use `~/` to denote the application root path and `+/` in nested routes to append to the parent route. |
| `url`            | `Prop<string>` | Url binding. Bind this to the global `url` variable.                                                                                       |
| `prefix`         | `boolean`      | Match route even if given `route` is only a prefix of the current `url`. Used when a route contains nested subroutes.                      |
| `params`         | `Prop<object>` | Params binding. Matched route parameters will be stored inside.                                                                            |