# Router

**`sonic-router`** watches the location (pathname + hash) and renders the views whose route matches. From Lit, pass a `.routes` map of path patterns to render functions; use **`sonic-redirect`** to navigate when a value appears in a data provider.

## Static routes

Each key is tested against the pathname + hash, first as a RegExp, then as a [url-pattern](https://www.npmjs.com/package/url-pattern). Every matching route renders; the `fallback` key renders when none does. The demo links append a second hash so the doc page itself stays loaded.

<docs-lit-demo for="docs-router-basic-demo"></docs-lit-demo>

Set `.routes` as a **property** binding: render functions cannot go through an HTML attribute.

## Route parameters

A url-pattern key such as `#flights/:code` passes an object (`{ code }`) to its render function. A RegExp key passes its capturing groups as an array, in order.

<docs-lit-demo for="docs-router-params-demo"></docs-lit-demo>

## Base path

By default, url-pattern keys accept any leading slashes and RegExp keys are not anchored. Set `basePath` to require a prefix: it is prepended to every url-pattern key, and to RegExp keys after `^`.

<sonic-code language="html" noPreview>
  <template>
&lt;sonic-router basePath="/app"&gt;&lt;/sonic-router&gt;
&lt;!-- "/fleet" now matches /app/fleet only --&gt;
  </template>
</sonic-code>

## HTML templates

Without Lit, declare `<template data-route>` children. A `title` attribute sets `document.title` and `data-fallback` marks the template shown when nothing matches. `dataProviderExpression` wraps the content in an element whose `dataProvider` is built from the route (`$1` or `:name`), as in [States](/core/components/functional/states).

<sonic-code language="html" noPreview>
  <template>
&lt;sonic-router fallBackRoute="/departures"&gt;
  &lt;template data-route="/departures" title="Departures"&gt;…&lt;/template&gt;
  &lt;template data-route="/flights/:code" dataProviderExpression="flights/:code"&gt;
    &lt;sonic-value key="status"&gt;&lt;/sonic-value&gt;
  &lt;/template&gt;
&lt;/sonic-router&gt;
  </template>
</sonic-code>

`fallBackRoute` navigates to its URL when no route matches, even if a `data-fallback` template exists. A `routes.fallback` function prevents it.

## Redirect on data

**`sonic-redirect`** navigates to `to` once the value at `onData` (dot path) in its data provider is set and truthy. Here, checking in sends the passenger to the boarding page.

<sonic-code language="html" noPreview>
  <template>
&lt;sonic-redirect to="#boarding" dataProvider="checkin" onData="checkedIn"&gt;&lt;/sonic-redirect&gt;
&lt;div formDataProvider="checkin"&gt;
  &lt;sonic-button radio name="checkedIn" value="yes"&gt;Check in&lt;/sonic-button&gt;
&lt;/div&gt;
  </template>
</sonic-code>

Objects do not trigger the redirect: point `onData` at a scalar such as `passenger.id`.

## API reference

`sonic-router`

| Attribute | Values | Description |
|-----------|--------|-------------|
| `routes` | object (property) | Render functions keyed by RegExp or url-pattern, plus `fallback` |
| `basePath` | string | Prefix required before every route. Default: any leading slashes for url-pattern, no anchor for RegExp |
| `fallBackRoute` | string | URL to navigate to when no route matches and `routes.fallback` is not set |

| Template attribute | Description |
|--------------------|-------------|
| `data-route` | RegExp or url-pattern matched against the location |
| `data-fallback` | Template shown when no route matches |
| `title` | Sets `document.title` when the template renders |
| `dataProviderExpression` | Builds the `dataProvider` of a wrapper around the content from `$1`… or `:name` |

| Slot | Description |
|------|-------------|
| *(default)* | `<template data-route>` children |

`sonic-redirect`

| Attribute | Values | Description |
|-----------|--------|-------------|
| `to` | string | Destination. A value starting with `#` only changes the hash |
| `dataProvider` | string | Provider to watch. Inherited from the closest ancestor when omitted |
| `onData` | string (required) | Dot path of the value that triggers the redirect when truthy |
| `onAdded` | boolean | Redirects as soon as the element renders, without waiting for data |
| `pushState` · `replaceState` | boolean | Navigates with `history.pushState` or `history.replaceState` instead of a full load. Ignored for `#` destinations |

No slots.