Lit UI Router

Appearance

API Overview ​

This guide provides a quick overview of the lit-ui-router API. For detailed type signatures and complete documentation, see the API Reference.

Installation ​

bash
npm install lit-ui-router
# or
pnpm add lit-ui-router

Quick Start ​

ts
import { UIRouterLit, uiSref, uiSrefActive, LitStateDeclaration } from 'lit-ui-router';
import { hashLocationPlugin } from '@uirouter/core';
import { html } from 'lit';

// 1. Create router and add location plugin
const router = new UIRouterLit();
router.plugin(hashLocationPlugin);

// 2. Define states
const states: LitStateDeclaration[] = [
  { name: 'home', url: '/home', component: () => html`<h1>Home</h1>` },
  { name: 'users', url: '/users', component: UserListElement },
];

// 3. Register states and start
states.forEach((state) => router.stateRegistry.register(state));
router.urlService.rules.initial({ state: 'home' });
router.start();
html
<!-- 4. Use in your app -->
<ui-router .uiRouter="${router}">
  <nav>
    <a ${uiSref('home')} ${uiSrefActive({ activeClasses: ['active'] })}>Home</a>
    <a ${uiSref('users')} ${uiSrefActive({ activeClasses: ['active'] })}>Users</a>
  </nav>
  <ui-view></ui-view>
</ui-router>

Core Concepts ​

Router ​

UIRouterLit is the main router class. It extends @uirouter/core's UIRouter with Lit-specific view handling.

Components ​

  • <ui-router> - Root component that provides router context to descendants
  • <ui-view> - Viewport that renders the component for the current state

Directives ​

  • uiSref - Creates navigation links to states
  • uiSrefActive - Adds CSS classes when linked state is active

State Declaration ​

LitStateDeclaration defines a state with its URL and component.

Component Styles ​

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

Inline Template Function (simplest)

ts
{ name: 'home', url: '/', component: () => html`<h1>Home</h1>` }

Template with Route Parameters

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

Template with Resolved Data

ts
{
  name: 'users',
  url: '/users',
  component: (props) => html`
    <ul>${props?.resolves?.users?.map(u => html`<li>${u.name}</li>`)}</ul>
  `,
  resolve: [{ token: 'users', resolveFn: () => fetchUsers() }]
}

LitElement Class (for complex components with lifecycle/state)

ts
{ name: 'dashboard', url: '/dashboard', component: DashboardElement }
StyleBest For
() => html`...`Simple static views
(props) => html`...`Views needing params or resolves
MyElementComplex views with lifecycle, state, or styles

Lifecycle Hooks ​

Components can implement these interfaces to respond to routing events:

Injected Props ​

Routed components receive UIViewInjectedProps with:

  • router - The UIRouter instance
  • transition - The current transition
  • resolves - Resolved data from state declarations

Location Plugins ​

Import from @uirouter/core:

ts
import { hashLocationPlugin, pushStateLocationPlugin } from '@uirouter/core';

// Hash URLs: /#/home
router.plugin(hashLocationPlugin);

// HTML5 pushState: /home
router.plugin(pushStateLocationPlugin);

See the @uirouter/core location plugins documentation:

Further Reading ​