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. Companion packages have their own home — see Companion Packages.

Installation

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

Entry Points

Import	Effect
import { ... } from 'lit-ui-router'	Full API. Any value import registers the <ui-router>/<ui-view> custom elements as a side effect.
import { ... } from 'lit-ui-router/pure'	The same full API — element classes included — with no registration and no HTMLElementTagNameMap globals.
import 'lit-ui-router/register'	Registration only: defines <ui-router>/<ui-view> and carries their HTMLElementTagNameMap entries.
import 'lit-ui-router/ui-view.register'	Single-element registration: defines just that element with its tag-map entry (ui-router.register ditto).
import type { ... } from 'lit-ui-router'	Types are erased at compile time — always free, from any entry.

Quick Start

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();

<!-- 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)

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

Template with Route Parameters

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

Template with Resolved Data

{
  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)

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

Style	Best For
() => html`...`	Simple static views
(props) => html`...`	Views needing params or resolves
MyElement	Complex views with lifecycle, state, or styles

Lifecycle Hooks

Components can implement these interfaces to respond to routing events:

• UiOnExit - Called before navigating away (can cancel navigation)
• UiOnParamsChanged - Called when route parameters change

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:

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:

• PushStateLocationService - HTML5 history API
• HashLocationService - Hash-based URLs

Companion Packages

lit-ui-router is the core package; optional companion packages layer on extra integrations — MobX bindings and the Navigation API location plugin, each independently versioned with its own guide and API reference. See Companion Packages.

Further Reading

• Tutorial - Step-by-step guide
• API Reference - Complete type documentation
• @uirouter/core docs - Core router documentation