lit-ui-router

Published packages

Package	npm	GitHub Release	Published diff
lit-ui-router
lit-ui-router-mobx
ui-router-navigation-location-plugin
ui-router-server
eslint-plugin-lit-ui-router
lit-ui-router-effect
lit-ui-router-ssr

Legend

Badge	Meaning
	The npm release matches main
	Unreleased ship-affecting changes on main

The workers-builds badge at the top is the same kind of signal for the deploy pipeline that ships lit-ui-router.dev — see CD-pipeline verification signal for what it diffs and what each color means.

---

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, with aria-current on active links out of the box
• Attribute-part forms - srefHref, srefActiveClass and srefAriaCurrent bind the same links from inside the attribute, so the href is real markup a static analyser or server renderer can read — see the API overview

Get Started

• Documentation - Full docs, tutorials, and API reference
• Examples - Try live examples on StackBlitz
• Sample apps - The same non-trivial app in two reactivity idioms (vanilla and MobX), compared side-by-side
• 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, LitStateDeclaration } from 'lit-ui-router';

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

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

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 }