<script type="module">
import routerComponent from 'https://cdn.skypack.dev/router-component';
</script>
README
<router-component>
A simple, declarative router component for single-page apps that allows you to load Web Components
dynamically when urls are requested, without performing a hard reload of the entire page.
Benefits
Very lightweight (there is very little code in this library)
Only provides routing needs and nothing more
Easy, declarative html syntax -- no complex configuration files or routing engines
Automatically intercepts all <a> tags on a page (that contain relative hrefs) to prevent them from causing page
reloads, which use pushState() API.
Installation
npm i router-component
Prerequisites
This library assumes you are using a browser that supports Web Components
and that you are using them as your routed elements. They are the future of the web and are already implemented
natively in browsers.
For advanced usage of this library, you will need to know
Regular Expressions and how
they work in JavaScript.
Usage
Basic Example
<!-- index.html -->
<html>
<head>
<script type="module" src="node_modules/router-component/dist/router-component.js"></script>
<script type="module">
customElements.define('first-page', class extends HTMLElement {
connectedCallback() {
this.innerHTML = `
Navigated to ${window.location.pathname} <br />` + //"/"
`Go to <a href="/second/view">second page</a>.`
;
}
});
customElements.define('second-page', class extends HTMLElement {
connectedCallback() {
this.innerHTML = `
Navigated to ${window.location.pathname} <br />` + // "/second/view" OR "/second/view/"
`Go to <a href="/doesnt/work">a page that doesnt exist</a>.`
;
}
});
customElements.define('page-doesnt-exist', class extends HTMLElement {
connectedCallback() {
this.innerHTML = `<p>Wrong page, go to <a href="/">first page again</a></p>`;
}
});
</script>
</head>
<body>
<router-component>
<first-page path="^/(index.html)?
The number of milliseconds to delay the router's scrolling to the anchored element on a page
show-delay
Number
The number of milliseconds to delay before the router adds each page to the DOM and triggers its connectedCallback (useful to implement some sort of animation or transition of a previous page first)
hide-delay
Number
The number of milliseconds to delay before the router removes each page from the DOM and triggers its disconnectedCallback
Event that is triggered when the page is removed from the DOM. The page being removed is passed as the detail property on the emitted event.
Route API
Each child element of <router-component> should be a
CustomElement so that the following attributes
can be passed to them:
Option
Type
Description
path
String
A regex expression that the browser URL needs to match in order for the component to render. Capture groups are also supported to allow for dynamic parameters in URLs.
search-params
String
A search string regex that the requested page would need to have in order to match. Setting this value to foo=[bar\|baz] would match index.html?foo=bar for instance)
The goal of this package is to leverage the use of existing browser APIs, while providing only a few key pieces of logic that make routing easier, which is identified below.
Changing Routes
There are two ways that a route can be changed.
By clicking on a relative link that is nested within a route element or
Each method will trigger the route-changed event that is dispatched by the router component itself, which is illustrated in the next section below.
In the rare case you would like to push a new state or change the current location without triggering a new route, you
can pass triggerRouteChange flag like this: