lit-ui-router

A UI-Router implementation for Lit.

Installation

npm install lit-ui-router

Quick Start

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

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

const states: LitStateDeclaration[] = [
  { name: 'home', url: '/', component: () => html`<h1>Home</h1>` },
  { name: 'about', url: '/about', component: () => html`<h1>About</h1>` },
];
states.forEach((state) => router.stateRegistry.register(state));

router.start();

Entry Points

| Import | Effect | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | import { ... } from 'lit-ui-router' | The router, the elements, the directives and the controllers. Any value import registers the <ui-router>/<ui-view> custom elements as a side effect. | | import { ... } from 'lit-ui-router/pure' | The same 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 { ... } from 'lit-ui-router/context' | The only home of the context-request key, event and request helper, and of the tree-less router hand-off — no elements, and nothing from lit. | | import type { ... } from 'lit-ui-router' | Types are erased at compile time — always free, from any entry. |

The root entry is exactly pure + register: reach for lit-ui-router/pure when you need the APIs (or the element classes themselves, e.g. for scoped registries or custom tag names) without touching the global registry, and pair it with lit-ui-router/register — or a single *.register entry — to opt into registration explicitly.

Development and Production Builds

Every entry point above publishes twice: dist/development/*.js alongside dist/*.js, picked by the development export condition, which bundlers resolve automatically. Nothing to configure.

The development build carries three console warnings — uiSref writing an inert href, uiSrefActive taking over an aria-current it did not set, and any binding finding no <ui-router> ancestor. Each is gated on lit's own development build as well, and none of them, message text included, is present in a production bundle. See the Development & Production Builds guide for what each warning means and how the split is verified.

Component Styles

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

Reacting to Transitions

Any element (routed or not) can stay synchronized with the router using the TransitionController reactive controller. It registers transition hooks when the host connects, calls host.requestUpdate() on matching transitions, and deregisters everything when the host disconnects — no manual requestUpdate() plumbing or leaked hooks.

import { TransitionController } from 'lit-ui-router';

class NavHeader extends LitElement {
  private transitions = new TransitionController(this);

  render() {
    // Re-evaluated after every successful transition
    return html`Current state: ${this.transitions.current?.name}`;
  }
}

Scope it to specific states or react to parameter changes with a callback:

class UserDetail extends LitElement {
  private transitions = new TransitionController(this, {
    criteria: { to: 'users.detail' },
    callback: () => this.loadUser(this.transitions.params.userId),
  });
}

Navigation Links

uiSref and uiSrefActive bind a link from the element; srefHref, srefActiveClass and srefAriaCurrent bind the same link from inside the attribute it writes, so the href is real markup a static analyser or server renderer can read — see Attribute-part forms.

Documentation

Visit lit-ui-router.dev for full documentation, tutorials, and API reference.