Lit UI Router

lit-ui-router / uiSrefActive

Variable: uiSrefActive ​

ts
const uiSrefActive: (params) => DirectiveResult<typeof UiSrefActiveDirective>;

Defined in: packages/lit-ui-router/src/ui-sref-active.ts:927

Directive that adds CSS classes based on active router state.

The uiSrefActive directive watches the current router state and applies CSS classes to elements when their associated states are active. It supports both "active" classes (applied when the state or any child state is active) and "exact" classes (applied only when the exact state is active).

On link elements (<a>, <area>, [role="link"]) it also sets aria-current="page" while the exact state is active, and removes the attribute otherwise, so assistive technology gets the same "you are here" signal as the active CSS class. Other elements opt in by passing ariaCurrentValue explicitly.

Arguments:

  • params - Configuration object (see UiSrefActiveParams) with activeClasses, exactClasses, ariaCurrentValue, and optional state/params

Parameters ​

ParameterType
paramsPartial<UiSrefActiveParams>

Returns ​

DirectiveResult<typeof UiSrefActiveDirective>

Examples ​

Basic usage with nested uiSref

ts
import { uiSref, uiSrefActive } from 'lit-ui-router';
import { html } from 'lit';

html`
  <a ${uiSref('home')} ${uiSrefActive({ activeClasses: ['active'] })}>
    Home
  </a>
`

With exact matching

ts
html`
  <a ${uiSref('users')}
     ${uiSrefActive({
       activeClasses: ['nav-active'],
       exactClasses: ['nav-exact']
     })}>
    Users
  </a>
`

Container mode (watches nested uiSref directives)

ts
html`
  <nav ${uiSrefActive({ activeClasses: ['section-active'] })}>
    <a ${uiSref('users')}>Users</a>
    <a ${uiSref('users.list')}>List</a>
    <a ${uiSref('users.create')}>Create</a>
  </nav>
`

Customizing or disabling aria-current

ts
html`
  <!-- a step in a multi-step flow -->
  <a ${uiSref('wizard.payment')}
     ${uiSrefActive({ activeClasses: ['active'], ariaCurrentValue: 'step' })}>
    Payment
  </a>

  <!-- opt a non-link element in; 'auto' keeps href off it -->
  <tr ${uiSref('.message', { messageId }, { assignHref: 'auto' })}
      ${uiSrefActive({ activeClasses: ['active'], ariaCurrentValue: 'true' })}>
  </tr>

  <!-- leave aria-current alone: the app manages it, and a value written
       here survives in every routing state -->
  <a ${uiSref('home')}
     aria-current="page"
     ${uiSrefActive({ activeClasses: ['active'], ariaCurrentValue: false })}>
    Home
  </a>

  <!-- mark the ancestor section as well as the current page:
       at `users` -> aria-current="page", at `users.detail` -> "location" -->
  <a ${uiSref('users')}
     ${uiSrefActive({
       activeClasses: ['active'],
       ariaCurrentValue: { exact: 'page', active: 'location' },
     })}>
    Users
  </a>

  <!-- ...or mark only the ancestor, never the page itself -->
  <a ${uiSref('users')}
     ${uiSrefActive({
       activeClasses: ['active'],
       ariaCurrentValue: { exact: false, active: 'location' },
     })}>
    Users
  </a>
`

Only an aria-current this directive wrote is removed again. A template-authored value therefore survives right up until the directive first writes one of its own — from that point the directive owns the attribute and will clear it on the next inactive render. Pair a template-authored value with ariaCurrentValue: false to keep it for good.

Explicit state (without nested uiSref)

ts
html`
  <div ${uiSrefActive({
    state: 'dashboard',
    activeClasses: ['dashboard-active']
  })}>
    Dashboard content
  </div>
`

See ​