# @mwillbanks/tuil-router

Source: /tuil/docs/reference/packages/router
Locale: en

Typed terminal routes, guards, history, loaders, layouts, and focus restoration for tuil.



## Overview [#overview]

Typed terminal routes, guards, history, loaders, layouts, and focus restoration for tuil.

`@mwillbanks/tuil-router` is independently installable and also participates in the
umbrella `@mwillbanks/tuil` runtime where applicable.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @mwillbanks/tuil-router
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @mwillbanks/tuil-router
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @mwillbanks/tuil-router
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @mwillbanks/tuil-router
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## How it operates [#how-it-operates]

The terminal router matches typed routes, executes guards and loaders, manages history and layouts, exposes navigation surfaces, and restores focus after transitions.

<Mermaid
  chart="flowchart LR
  S0[&#x22;intent&#x22;]
  S1[&#x22;match&#x22;]
  S2[&#x22;before guards&#x22;]
  S3[&#x22;loader&#x22;]
  S4[&#x22;commit&#x22;]
  S5[&#x22;focus restore&#x22;]
  S6[&#x22;after hooks&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3
  S3 --> S4
  S4 --> S5
  S5 --> S6"
/>

## API [#api]

| API                                                                                    | Signature                         | Description                             |
| -------------------------------------------------------------------------------------- | --------------------------------- | --------------------------------------- |
| [`createRouter`](/tuil/docs/reference/packages/router/api/create-router)                    | `function createRouter`           | Public function createRouter.           |
| [`defineRoutes`](/tuil/docs/reference/packages/router/api/define-routes)                    | `function defineRoutes`           | Public function defineRoutes.           |
| [`FocusSnapshot`](/tuil/docs/reference/packages/router/api/focus-snapshot)                  | `interface FocusSnapshot`         | Public interface FocusSnapshot.         |
| [`NavigationEntry`](/tuil/docs/reference/packages/router/api/navigation-entry)              | `interface NavigationEntry`       | Public interface NavigationEntry.       |
| [`NavigationSurface`](/tuil/docs/reference/packages/router/api/navigation-surface)          | `type NavigationSurface`          | Public type NavigationSurface.          |
| [`NavigationTarget`](/tuil/docs/reference/packages/router/api/navigation-target)            | `type NavigationTarget`           | Public type NavigationTarget.           |
| [`route`](/tuil/docs/reference/packages/router/api/route)                                   | `function route`                  | Public function route.                  |
| [`RouteContext`](/tuil/docs/reference/packages/router/api/route-context)                    | `interface RouteContext`          | Public interface RouteContext.          |
| [`RouteDefinition`](/tuil/docs/reference/packages/router/api/route-definition)              | `interface RouteDefinition`       | Public interface RouteDefinition.       |
| [`RouteMatch`](/tuil/docs/reference/packages/router/api/route-match)                        | `interface RouteMatch`            | Public interface RouteMatch.            |
| [`RouterEvent`](/tuil/docs/reference/packages/router/api/router-event)                      | `interface RouterEvent`           | Public interface RouterEvent.           |
| [`RouterEventType`](/tuil/docs/reference/packages/router/api/router-event-type)             | `type RouterEventType`            | Public type RouterEventType.            |
| [`RouterState`](/tuil/docs/reference/packages/router/api/router-state)                      | `interface RouterState`           | Public interface RouterState.           |
| [`TerminalRouter`](/tuil/docs/reference/packages/router/api/terminal-router)                | `class TerminalRouter`            | Public class TerminalRouter.            |
| [`TerminalRouterOptions`](/tuil/docs/reference/packages/router/api/terminal-router-options) | `interface TerminalRouterOptions` | Public interface TerminalRouterOptions. |

## Events and lifecycle [#events-and-lifecycle]

`router:navigation-start`, `router:navigation-complete`, `router:navigation-cancel`, and `router:navigation-error` describe transition outcomes.

All subscriptions and registrations return a disposer or belong to an owning
runtime that disposes them in reverse order.

## Example [#example]

```tsx
import { createRouter, defineRoutes, route } from "@mwillbanks/tuil-router";

const router = createRouter(defineRoutes({ home: route({ path: "/" }) }));
await router.navigate("home");
```

## Related [#related]

* [Package architecture](/tuil/docs/concepts/packages)
* [Events](/tuil/docs/concepts/events)
* [Testing](/tuil/docs/guides/testing)