--- title: 'Browser Router' description: 'Add client-side SPA navigation to Ecopages sites with browser-router.' order: 5 --- import { RuiAlert, RuiAlertDescription, RuiAlertTitle } from '@ecopages/radiant-ui/alert'; import { CodeTabs } from '@/components/code-tabs'; # Client-Side Navigation The `@ecopages/browser-router` package enables Single Page Application (SPA) navigation behavior in your Ecopages application. It intercepts link clicks, fetches the next page via fetch, and uses [morphdom](https://github.com/patrick-steele-idem/morphdom) to efficiently diff and update only the parts of the DOM that changed. This preserves element state (like audio players, web component internals, or form values) and enables native View Transitions. Framework Compatibility

This package works with MPA-style rendering (KitaJS, Lit, vanilla JS).{' '} Not compatible with React/Preact, these frameworks manage their own virtual DOM. For React apps, use a framework-specific routing solution.

## Installation Please run the following command to install the package: ## Setup To enable client-side routing, initialize the router in your global script (e.g., `src/layouts/base-layout.script.ts`). Consistent Head Ordering Required

To prevent "Flash of Unstyled Content" (FOUC), ensure the router script is injected in a{' '} consistent order within the <head> across all pages.

Inconsistent ordering (e.g., script loaded between stylesheets on one page but after them on another) causes{' '} morphdom to detach and re-add stylesheets during navigation. Using a global layout script (like{' '} base-layout.script.ts) helps ensure this consistency.

The simplest approach is to use `createRouter`, which creates and starts the router in one call: ```typescript import { createRouter } from '@ecopages/browser-router/client'; const router = createRouter({ viewTransitions: true, }); ``` For manual control over when the router starts and stops, use the `EcoRouter` class directly: ```typescript import { EcoRouter } from '@ecopages/browser-router/client'; const router = new EcoRouter({ viewTransitions: true, }); router.start(); ``` ## Configuration You can customize the router behavior by passing an options object: | Option | Type | Default | Description | | :-------------------------------- | :------------------------------ | :------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `linkSelector` | `string` | `'a[href]'` | Selector for links to intercept. | | `documentElementAttributesToSync` | `string[]` | `['lang', 'dir', 'data-eco-document-owner']` | `` attributes to sync from the incoming document. Attributes not listed here are preserved on the live page. | | `persistAttribute` | `string` | `'data-eco-persist'` | Attribute to mark elements that should persist across navigations. | | `reloadAttribute` | `string` | `'data-eco-reload'` | Attribute (on link or element) to force a full hard reload. | | `scrollBehavior` | `'top' \| 'preserve' \| 'auto'` | `'top'` | Controls scroll behavior after navigation. | | `smoothScroll` | `boolean` | `false` | Enables smooth scrolling. | | `viewTransitions` | `boolean` | `true` | Enables [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API). Disables UA root crossfade by default. `false` disables. | | `prefetch` | `PrefetchConfig \| false` | `Object` | Configuration for prefetching behavior. | ### View Transitions The browser router supports the native View Transitions API. When enabled (default), the router opts the document out of the UA root view-transition group so dark themes do not flash lighter. `startViewTransition` runs only when the current or incoming page has matching `data-view-transition` elements for shared-element morphs. **Visual check:** dark background → SPA navigate → no lighter flash with defaults. To create a shared element transition, simply add the `data-view-transition` attribute to matching elements on different pages: ```html

...

``` The router automatically handles the transition names and ensures a clean "morph" animation (hiding the old snapshot to prevent ghosting) by default. #### Directives You can control the transition behavior using `data-view-transition-animate`: | Value | Description | | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | | **`morph`** | (Default) Disables the cross-fade animation, resulting in a clean geometric morph. Ideal for shared element transitions to prevent "ghosting". | | **`fade`** | Uses the standard browser cross-fade animation. Useful if you specifically want the old and new elements to fade into each other. | ```html

...

``` #### Duration You can also control the speed of a specific transition using `data-view-transition-duration`: ```html

...

``` #### Update History | `updateHistory` | `boolean` | `true` | Whether to push a new entry to the browser history for each client-side navigation. | | `smoothScroll` | `boolean` | `true` | Whether to use smooth scrolling when adjusting scroll position after navigation. | ### Example with Options ```typescript const router = createRouter({ viewTransitions: true, scrollBehavior: 'preserve', linkSelector: 'a:not([data-no-route])', documentElementAttributesToSync: ['lang', 'dir', 'data-theme'], }); ``` Use `documentElementAttributesToSync` to formalize ownership of root `` attributes. The default keeps navigation metadata in sync while preserving client-managed state such as theme classes or data attributes. If you need lower-level control without overriding the router pipeline, import the document sync helpers directly: ```typescript import { createRouter, DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC, syncDocumentElementAttributes, } from '@ecopages/browser-router'; const router = createRouter(); document.addEventListener('eco:before-swap', (event) => { syncDocumentElementAttributes(document, event.detail.newDocument, [ ...DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC, 'data-theme', ]); }); ``` ## Features ### Persistence Elements marked with `data-eco-persist` are **never recreated** during navigation. morphdom recognizes these elements by their persist ID and skips updating them entirely, preserving their internal state (event listeners, web component state, form values, audio playback, etc.). Add the `data-eco-persist` attribute with a unique ID: ```tsx