Skip to content

RoutingTarget.md

Latest commit

 

History

History
155 lines (112 loc) · 4.71 KB

RoutingTarget.md

File metadata and controls

155 lines (112 loc) · 4.71 KB
Raw

<r-route-target>

A web component that renders route components in response to navigation events.

Overview

<r-route-target> listens for NavigateRouteEvent events dispatched by the router and renders the appropriate component. Multiple targets can exist on a page, each identified by a unique name attribute.

Usage

Default Target

<r-route-target></r-route-target>

Routes without a target property render in the default (unnamed) target.

Named Targets

<div class="layout">
    <aside>
        <r-route-target name="sidebar"></r-route-target>
    </aside>
    <main>
        <r-route-target></r-route-target>
    </main>
    <aside>
        <r-route-target name="rightPanel"></r-route-target>
    </aside>
</div>

Route Configuration

Routes specify their target with the target property:

const routes: Route[] = [
    { name: "home", path: "/", componentTagName: "home-page" },
    { name: "user", path: "/users/:userName", target: "rightPanel", componentTagName: "user-profile" },
    { name: "menu", path: "/menu", target: "sidebar", componentTagName: "nav-menu" }
];

defineRoutes(routes);

Programmatic Navigation

navigate("user", { params: { userName: "john" }, target: "rightPanel" });

Route Component Registration

Components must be registered as custom elements before routing, unless the route loads them:

// Using componentTagName
const routes: Route[] = [
    { path: "/dashboard", componentTagName: "dashboard-page" }
];

// Using component reference
const routes: Route[] = [
    { path: "/dashboard", component: DashboardPage }
];

// Imported on first visit
const routes: Route[] = [
    {
        path: "/dashboard",
        componentTagName: "dashboard-page",
        load: () => import("./pages/DashboardPage"),
    }
];

See Loading a page on first visit.

Dialog Targets

Add the dialog attribute to render routes inside a native <dialog> element. This gives you focus trapping, a backdrop, and Escape-to-close for free.

<r-route-target name="modal" dialog></r-route-target>
const routes: Route[] = [
    { name: "preview", path: "/preview/:id", target: "modal", componentTagName: "item-preview" }
];

Style the backdrop with CSS:

r-route-target dialog::backdrop {
    background: rgba(0, 0, 0, 0.5);
}

Close the dialog programmatically:

const target = document.querySelector<RouteTarget>('r-route-target[name="modal"]');
target.close();

Per-Target Navigation History

Each <r-route-target> owns its own back/forward history. Navigations dispatched to a target are recorded; the Back/Forward Navigation section of the routing guide covers the public API (navigateBack, navigateForward, canGoBack, canGoForward) and the <r-link direction="back"> helper.

Histories are tied to the target's name. If a target is removed and a new target with the same name is later connected, its previous history is restored so back/forward keep working across layout transitions.

View Transitions

Route transitions are automatically animated using the View Transitions API when the browser supports it. The default effect is a crossfade. Customize with CSS:

::view-transition-old(root) {
    animation: slide-out 0.2s ease-out;
}

::view-transition-new(root) {
    animation: slide-in 0.2s ease-in;
}

Dialog targets do not use view transitions (the dialog open/close provides its own visual feedback).

Attributes

Attribute Type Description
name string Identifies this target for named routing. Unnamed targets receive routes without a target property.
dialog boolean When present, renders content inside a native <dialog> element with modal behavior.

Behavior

  1. Listens for NavigateRouteEvent on the document
  2. Ignores events targeting other named targets
  3. Creates the route's component element
  4. Replaces current children with the new component (with view transition animation)
  5. For dialog targets: opens the dialog as a modal when content arrives

Errors

Error Cause
Component with tagName '...' is not defined in customElements. Thrown by defineRoutes(): the route's componentTagName is not defined yet and the route has no load
Route '...' could not load <...>: its load() failed. The route's load() rejected; the cause is in the error context
Route '...' ran load(), but <...> is still not defined. The loaded module defines another tag, or none
Failed to find component for route The route has neither componentTagName nor component