README.md

UI-Router for Lit

lit-ui-router: State based routing for Lit (v2+)

---

lit-ui-router is a client-side Single Page Application routing framework for Lit.

Routing frameworks for SPAs update the browser's URL as the user navigates through the app. Conversely, this allows changes to the browser's URL to drive navigation through the app, thus allowing the user to create a bookmark to a location deep within the SPA.

UI-Router applications are modeled as a hierarchical tree of states. UI-Router provides a state machine to manage the transitions between those application states in a transaction-like manner.

Features

• Flexible Component Definitions - Use template functions, LitElement classes, or both
• State-based Routing - Hierarchical states with nested views
• Data Resolution - Fetch data before rendering with built-in resolve system
• Navigation Directives - uiSref and uiSrefActive for declarative navigation

Get Started

• Documentation - Full docs, tutorials, and API reference
• Examples - Try live examples on StackBlitz
• About UI-Router - Core concepts

The UI-Router package is distributed using npm, the node package manager.

npm install lit-ui-router

Import UIRouterLit into your project, register some states and you're good to go!

import { render, html } from 'lit';
import { hashLocationPlugin } from '@uirouter/core';
import { UIRouterLit } from 'lit-ui-router';

const router = new UIRouterLit();
router.plugin(hashLocationPlugin);

// Simple routes using template functions - no LitElement classes needed!
router.stateRegistry.register([
  { name: 'home', url: '/home', component: () => html`<h1>Home</h1>` },
  { name: 'about', url: '/about', component: () => html`<h1>About</h1>` },
]);

router.start();

render(
  html`<ui-router .uiRouter=${router}>
    <ui-view></ui-view>
  </ui-router>`,
  document.getElementById('root')!,
);

Component Styles

lit-ui-router supports multiple ways to define route components:

Style	Best For	Example
Template function	Simple views, prototyping	() => html`...`
Template with props	Views needing params/resolves	(props) => html`...`
LitElement class	Complex views with lifecycle	MyComponent

With Route Parameters

{
  name: 'user',
  url: '/user/:id',
  component: (props) => html`<h1>User ${props?.transition?.params().id}</h1>`
}

With LitElement Classes

For complex components with lifecycle, state, and styles:

{ name: 'dashboard', url: '/dashboard', component: DashboardElement }