Lit UI Router

lit-ui-router / SrefStatusController

Class: SrefStatusController ​

Defined in: packages/lit-ui-router/src/sref-status-controller.ts:142

A Lit ReactiveController that exposes a state's SrefStatus — active, exact, entering, exiting — to its host, so the host's own template decides what to do with it.

This is the composition path srefActiveClass cannot offer: a class attribute holds one toggling directive, so srefActiveClass and classMap cannot share it. Read the flags here instead and pass them to classMap, to aria-current, to a ?disabled, to anything.

The controller registers its hooks when the host connects and deregisters them on hostDisconnected, so nothing leaks when hosts come and go. It calls host.requestUpdate() only when one of the four flags or the watched targets actually changed, so transitions that leave the link alone cost no render.

Examples ​

Composing with classMap and aria-current

ts
import { html, LitElement } from 'lit';
import { classMap } from 'lit/directives/class-map.js';
import { srefHref, SrefStatusController } from 'lit-ui-router';

class NavLink extends LitElement {
  private users = new SrefStatusController(this, { state: 'users' });

  render() {
    return html`<a
      href=${srefHref('users')}
      class=${classMap({ 'nav-link': true, active: this.users.active, disabled: this.locked })}
      aria-current=${this.users.ariaCurrent()}
    >Users</a>`;
  }
}

With an explicit router instance

ts
// status is computed in the constructor, before the host ever connects
const status = new SrefStatusController(host, { state: 'users', router });

Re-target from a property setter

ts
class NavLink extends LitElement {
  private status = new SrefStatusController(this);

  @property() set state(state: string) {
    this.status.retarget({ state });
  }
}

Container mode: watch the links in the host's template

ts
class NavSection extends LitElement {
  // no `state`: every srefHref link below feeds this controller
  private section = new SrefStatusController(this);

  render() {
    return html`<li class=${classMap({ active: this.section.active })}>
      <a href=${srefHref('users')}>Users</a>
      <a href=${srefHref('users.create')}>New</a>
    </li>`;
  }
}

See ​

Implements ​

Constructors ​

Constructor ​

ts
new SrefStatusController(host, options?): SrefStatusController;

Defined in: packages/lit-ui-router/src/sref-status-controller.ts:162

Parameters ​

ParameterType
hostReactiveControllerHost & Element
optionsSrefStatusControllerOptions

Returns ​

SrefStatusController

Accessors ​

active ​

Get Signature ​

ts
get active(): boolean;

Defined in: packages/lit-ui-router/src/sref-status-controller.ts:199

The target state, or a child of it, is active.

Returns ​

boolean

entering ​

Get Signature ​

ts
get entering(): boolean;

Defined in: packages/lit-ui-router/src/sref-status-controller.ts:209

A transition in flight is entering the target state.

Returns ​

boolean

exact ​

Get Signature ​

ts
get exact(): boolean;

Defined in: packages/lit-ui-router/src/sref-status-controller.ts:204

The target state is itself the active state.

Returns ​

boolean

exiting ​

Get Signature ​

ts
get exiting(): boolean;

Defined in: packages/lit-ui-router/src/sref-status-controller.ts:214

A transition in flight is exiting the target state.

Returns ​

boolean

router ​

Get Signature ​

ts
get router(): 
  | UIRouter
  | undefined;

Defined in: packages/lit-ui-router/src/sref-status-controller.ts:186

The observed UIRouter instance.

undefined until provided via SrefStatusControllerOptions.router or discovered from an ancestor <ui-router> on connect.

Returns ​

| UIRouter | undefined

status ​

Get Signature ​

ts
get status(): SrefStatus | undefined;

Defined in: packages/lit-ui-router/src/sref-status-controller.ts:194

The merged SrefStatus of every watched target, or undefined while there is no router or no target.

Returns ​

SrefStatus | undefined

targetStates ​

Get Signature ​

ts
get targetStates(): TargetState[];

Defined in: packages/lit-ui-router/src/sref-status-controller.ts:219

The states being watched: the named one, or the enclosed links'.

Returns ​

TargetState[]

Methods ​

ariaCurrent() ​

ts
ariaCurrent(value?): typeof nothing | AriaCurrentValue;

Defined in: packages/lit-ui-router/src/sref-status-controller.ts:243

The aria-current token for the current status, or nothing to leave the attribute off — srefAriaCurrent's rules, as a value to bind: 'page' while the exact state is active, nothing otherwise.

Parameters ​

ParameterTypeDescription
value?| AriaCurrentValue | AriaCurrentValuesanother token, or { exact, active } to mark an active ancestor too. See AriaCurrentValues.

Returns ​

typeof nothing | AriaCurrentValue

retarget() ​

ts
retarget(params): void;

Defined in: packages/lit-ui-router/src/sref-status-controller.ts:228

Points the controller at another state — for a host that takes the state as a property. Replaces state, params and options wholesale, keeps the router, and refreshes.

Parameters ​

ParameterType
paramsSrefTargetParams

Returns ​

void