Skip to content

RoutingTarget.md

Latest commit

 

History

History
142 lines (101 loc) · 4.11 KB

RoutingTarget.md

File metadata and controls

142 lines (101 loc) · 4.11 KB
Raw

RouteTarget

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:

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

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

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
RouteError: CustomElement has not been registered Route's componentTagName not defined via customElements.define()
RouteError: Failed to find component Route's component class not registered