Router Containers

In order to use a router in an application, it must be attached to the DOM with a router container. Router containers are provided by the lwr-router-container component.

A router container provides navigation context. This means that the router container is responsible for processing all navigation wires and events from its descendants in the DOM. In the following example, those descendants are my-nav and lwr-outlet.

1<template>
2    <lwr-router-container
3        router={router}
4        onhandlenavigation={handleNavigation}
5        onprenavigate={preNavigate}
6        onpostnavigate={postNavigate}
7        onerrornavigate={errorNavigate}>
8        <my-nav></my-nav>
9        <lwr-outlet></lwr-outlet>
10    </lwr-router-container>
11</template>

1import { LightningElement } from "lwc";
2import { createRouter } from "lwr/router";
3import { ROUTE_DEFINITIONS } from "./routeDefinitions";
4
5export default class MyApp extends LightningElement {
6  router = createRouter({ routes: ROUTE_DEFINITIONS });
7  approvedCategories = ["apps", "entrees", "sides", "desserts"];
8
9  handleNavigation(e: CustomEvent): void {
10    console.log("navigate() called with page reference:", e.detail);
11  }
12
13  preNavigate(e: CustomEvent): void {
14    const {
15      next: {
16        route: { pageReference },
17      },
18    } = e.detail;
19    const {
20      attributes: { cat },
21    } = pageReference;
22    console.log("navigation event incoming with page reference:", pageReference);
23    if (!this.approvedCategories.includes(cat)) {
24      // REJECT unapproved recipe categories
25      e.preventDefault();
26    }
27  }
28
29  postNavigate(e: CustomEvent): void {
30    const {
31      route: { pageReference },
32    } = e.detail;
33    console.log("navigated to page reference:", pageReference);
34  }
35
36  errorNavigate(e: CustomEvent): void {
37    const { code, message } = e.detail;
38    console.error(`navigation error -> ${code}: ${message}`);
39  }
40}

Router Container Events

A router container requires a router, and it fires these events:

onhandlenavigation

Dispatched when navigate(pageRef) is called.
event.preventDefault() cancels the navigation event.
event.detail is the PageReference.

onprenavigate

Dispatched when a navigation event is received and a RouteDefinition match is found.
event.preventDefault() cancels the navigation event.

event.detail is a RouteChange().

1interface RouteChange {
2current?: DomRoutingMatch; // the current location info
3next: DomRoutingMatch; // location info for the incoming nav event
4}

onpostnavigate

Dispatched when a navigation event has completed.

event.detail is a DomRoutingMatch for the current location.

1interface DomRoutingMatch {
2url: string; // e.g. "/recipes/desserts/010?units=metric&yummy=yes"
3route: RouteInstance;
4routeDefinition: RouteDefinition;
5}

onerrornavigate

Dispatched when there is an error processing a navigation event. (For example, no RouteDefinition match or prenavigate cancelation.)

event.detail is a MessageObject.

1interface MessageObject {
2code: string | number;
3message: string;
4level: number; // Fatal = 0, Error = 1, Warning = 2, Log = 3
5}

Next Steps

Simple Client-Side Routing: Create a Router demonstrates how to attach a router instance to a router container.

Developer Preview Feature

Feature is available as a developer preview. Feature is not generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Do not implement functionality developed with these commands or tools.