# Lit UI Router

> State-based routing for Lit

lit-ui-router is a client-side routing framework for Lit web components. It is an implementation of UI-Router built on the framework-agnostic `@uirouter/core`.

Install it with its peers, `lit` and `@uirouter/core`:

```bash
npm install lit-ui-router lit @uirouter/core
```

The Hello World starter is a Vite + TypeScript app. Copy it, then run `npm install` and `npm run dev` in `my-app`:

```bash
npx tiged simshanith/lit-ui-router/examples/helloworld my-app
```

[`helloworld-buildless`](https://github.com/simshanith/lit-ui-router/tree/main/examples/helloworld-buildless) is the same app in plain JavaScript: it runs with an import map and no build step, fetching `lit`, `@uirouter/core` and `lit-ui-router` from a CDN.

For a new SPA, the [Location Plugins](https://lit-ui-router.dev/guides/location-plugins.md) guide recommends `navigationLocationPlugin` where the browser has the Navigation API and `pushStateLocationPlugin` where it doesn't; the tutorial uses hash URLs, which need no host configuration.

## Table of Contents

### Introduction

- [Introduction](https://lit-ui-router.dev/introduction.md): What is Lit UI Router? State-based routing for Lit web components

### Tutorial

- [Hello World](https://lit-ui-router.dev/tutorial/helloworld.md): Getting started with lit-ui-router
- [Hello Solar System](https://lit-ui-router.dev/tutorial/hellosolarsystem.md): Learn about resolves and state parameters
- [Hello Galaxy](https://lit-ui-router.dev/tutorial/hellogalaxy.md): Learn about nested states and views
- [All Examples](https://lit-ui-router.dev/tutorial/live-examples.md): Every tutorial example app in one place, running live

### Guides

- [Guides](https://lit-ui-router.dev/guides.md): Task-oriented guides for lit-ui-router, grouped by topic
- [Location Plugins](https://lit-ui-router.dev/guides/location-plugins.md): Choosing a URL strategy - hash, pushState, or the Navigation API
- [Unmatched URLs (404)](https://lit-ui-router.dev/guides/unmatched-urls.md): Route unmatched URLs to a 404 state with urlService.rules.otherwise
- [Server-Side Routing](https://lit-ui-router.dev/guides/server-route-matching.md): Serve routing verdicts at the edge with ui-router-server - the spectrum from zero server requirements to a shared router, every level live on this site
- [Route Guards](https://lit-ui-router.dev/guides/route-guards.md): Protect states with transition hooks - the requiresAuth pattern
- [Loading and Error Views](https://lit-ui-router.dev/guides/loading-and-error-views.md): Show a pending indicator while a transition runs, render NOWAIT resolves behind a skeleton, and route failed transitions to an error view
- [Component Lifecycle Hooks](https://lit-ui-router.dev/guides/component-lifecycle.md): React to routing events from inside routed components with uiCanExit and uiOnParamsChanged
- [Routed Components](https://lit-ui-router.dev/guides/routed-components.md): Read a state's params in its routed component, and code-split the component's element module with a resolve or a lazyLoad future state
- [View Fallback Content](https://lit-ui-router.dev/guides/view-fallback-content.md): What <ui-view> renders when no routed component is active — the capture rules, the master/detail idiom, and prerendered shells
- [Reactive Components](https://lit-ui-router.dev/guides/reactive-components.md): Keep any component in sync with the router using TransitionController
- [Design System Links](https://lit-ui-router.dev/guides/design-system-links.md): Driving a design system's link component with uiSref, and why assignHref: true is the option for it
- [Development and Production Builds](https://lit-ui-router.dev/guides/development-builds.md): How lit-ui-router ships a separate development build, what warnings it carries, and why production bundles never contain them

### Companion Packages

- [Companion Packages](https://lit-ui-router.dev/packages.md): Optional packages that layer extra integrations on lit-ui-router — Effect, MobX and TC39 Signals bindings, the Navigation API location plugin, server-side routing verdicts, static prerendering, framework-agnostic Signals, Effect and MobX mirrors of the router, typed state names and params, and directive-aware ESLint rules — each independently versioned with its own guide and API reference
- [Effect](https://lit-ui-router.dev/packages/effect.md): The Effect packages for UI-Router — ui-router-effect holds the router's state in a SubscriptionRef, and lit-ui-router-effect provides ref-following Lit controllers
- [ESLint Plugin](https://lit-ui-router.dev/packages/eslint-plugin.md): Directive-aware linting with eslint-plugin-lit-ui-router — rules covering hrefless anchors, inert hrefs, aria-current conflicts and misplaced directives
- [MobX](https://lit-ui-router.dev/packages/mobx.md): The MobX packages for UI-Router — ui-router-mobx holds the router's state in an observable store, and lit-ui-router-mobx provides reaction-based Lit controllers
- [Navigation API Plugin](https://lit-ui-router.dev/packages/navigation-plugin.md): Manage URLs with the modern browser Navigation API using ui-router-navigation-location-plugin
- [UI-Router Registry](https://lit-ui-router.dev/packages/ui-router-registry.md): Typed state names and params for a @uirouter/core router with ui-router-registry, a types-only registry
- [Server-Side Routing](https://lit-ui-router.dev/packages/server.md): Honest HTTP verdicts for a static SPA with ui-router-server — the client's route table, running on the server or the edge
- [Signals](https://lit-ui-router.dev/packages/signals.md): The TC39 Signals packages for UI-Router — ui-router-signals mirrors the router's state into signals, and lit-ui-router-signals builds Lit controllers on that mirror
- [Static Prerendering](https://lit-ui-router.dev/packages/ssr.md): A ui-router-server mount table in, an emitted static site out, with lit-ui-router-ssr

#### Effect

- [UI-Router Effect](https://lit-ui-router.dev/packages/ui-router-effect.md): A framework-agnostic Effect SubscriptionRef of the router's current state with ui-router-effect
- [Effect Bindings](https://lit-ui-router.dev/packages/lit-ui-router-effect.md): A SubscriptionRef of the route and ref-following Lit controllers with lit-ui-router-effect

##### ui-router-effect

- [ui-router-effect](https://lit-ui-router.dev/api/ui-router-effect.md)

##### lit-ui-router-effect

- [lit-ui-router-effect](https://lit-ui-router.dev/api/lit-ui-router-effect.md)

#### MobX

- [UI-Router MobX](https://lit-ui-router.dev/packages/ui-router-mobx.md): A framework-agnostic MobX observable store of the router's current state with ui-router-mobx
- [MobX Bindings](https://lit-ui-router.dev/packages/lit-ui-router-mobx.md): Observable router state and reaction-based controllers with lit-ui-router-mobx

##### ui-router-mobx

- [ui-router-mobx](https://lit-ui-router.dev/api/ui-router-mobx.md)

##### lit-ui-router-mobx

- [lit-ui-router-mobx](https://lit-ui-router.dev/api/lit-ui-router-mobx.md)

#### Navigation Location

- [ui-router-navigation-location-plugin](https://lit-ui-router.dev/api/navigation-location-plugin.md)

#### Registry

- [ui-router-registry](https://lit-ui-router.dev/api/ui-router-registry.md)

#### Server

- [ui-router-server](https://lit-ui-router.dev/api/ui-router-server/index.md)

#### Signals

- [UI-Router Signals](https://lit-ui-router.dev/packages/ui-router-signals.md): A framework-agnostic TC39 Signals mirror of the router's current state with ui-router-signals
- [Signals Bindings](https://lit-ui-router.dev/packages/lit-ui-router-signals.md): Watcher-based Lit controllers over TC39 Signals of the route with lit-ui-router-signals

##### ui-router-signals

- [ui-router-signals](https://lit-ui-router.dev/api/ui-router-signals.md)

##### lit-ui-router-signals

- [lit-ui-router-signals](https://lit-ui-router.dev/api/lit-ui-router-signals.md)

#### SSR

- [lit-ui-router-ssr](https://lit-ui-router.dev/api/lit-ui-router-ssr.md)

### Sample App

- [Sample App](https://lit-ui-router.dev/sample-app.md): The lit-ui-router sample app — a webmail + contacts client — and every live mount it runs behind on lit-ui-router.dev, one per point on the server-support spectrum

### API

- [API Overview](https://lit-ui-router.dev/api.md)
- [lit-ui-router](https://lit-ui-router.dev/api/reference.md)