@capitec/omni-router
Framework agnostic, zero dependency, client-side web component router
[Introduction] [Usage] [API Reference] [Contributors] [License]
Omni Router is a simple client-side page router for single page application (SPA) web component projects that enable you to add animated URL based page navigation to your web app.
Core features of the library include:
- Framework Agnostic - The router is provided as a standard HTML web components, that can be used in VanillaJS or within any framework, e.g. Lit, React, Vue, Angular, etc.
- Web Components - The router has been specifically built to route pages built using web components.
-
Lazy Loading - Web component pages can be lazy loaded using
import('...'). - Route Guards - Routes can be protected using guard functions that prevent routing based on your app logic, e.g. check if the user is logged in.
- Animations - Pages can be animated in and out of view when routing, e.g. fade, slide, pop, etc.
- Browser History - Integrates with the browser history API to push, pop, and replace paths.
- Mobile Friendly - Navigating back reverses the route load animation, allowing mobile-like user experiences e.g. sliding routes in and out.
- Lightweight - The library is small and comes with zero dependencies, minimizing bloat to your project.
1️⃣ Install the library in your project.
npm install @capitec/omni-router2️⃣ Specify a base href location in your index.html to use as root for page navigation.
<base href="/">3️⃣ Import the Router package.
// JS import
import '@capitec/omni-router';
// or HTML import
<script type="module" src="/node_modules/omni-router/dist/index.js"></script>4️⃣ Place the <omni-router> tag in your web page, all routes will be rendered in this container.
<omni-router></omni-router>5️⃣ Define the pages you will route to.
// Register the app routes.
Router.addRoute({
name: 'view-fade',
title: 'Fade',
path: '/fade',
animation: 'fade',
load: () => import('./views/ViewFade'),
isDefault: true
});
// Load the route matching the current browser path.
Router.load();This example sets up a simple web page containing the Omni Router. Routes are registered on page load to navigate to individual web component pages using fade, slide, and pop animations.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Omni Router Demo</title>
<base href="/">
<script type="module">
import { Router } from '@capitec/omni-router';
// Register the app routes.
Router.addRoute({
name: 'view-fade',
title: 'Fade',
path: '/fade',
animation: 'fade',
load: () => import('./views/ViewFade'),
isDefault: true
});
Router.addRoute({
name: 'view-slide',
title: 'Slide',
path: '/slide',
animation: 'slide',
load: () => import('./views/ViewSlide')
});
Router.addRoute({
name: 'view-pop',
title: 'Pop',
path: '/pop',
animation: 'pop',
load: () => import('./views/ViewPop')
});
Router.addRoute({
name: 'view-guarded',
title: 'Guarded Route',
path: '/guarded',
load: () => import('./views/ViewGuarded'),
guard: () => !this._isUserLoggedIn()
});
Router.addRoute({
name: 'view-fallback',
title: 'Fallback Route',
path: '/error404',
load: () => import('./views/ViewFallback'),
isFallback: true
});
// Load the route matching the current browser path.
Router.load();
</script>
<script type="module" src="./AppShell.js"></script>
</head>
<body>
<omni-router></omni-router>
</body>
</html>// view/ViewFade.js
import { Router } from '@capitec/omni-router';
class ViewFade extends HTMLElement {
constructor() {
super();
// Create the DOM content template.
const template = document.createElement('template');
template.innerHTML = `
<style>
:host {
.background-color: white;
}
</style>
<h1>Hello World</h1>
<button id="back">⬅ Go Back</button>
`;
// Create a shadow root for the content.
this.attachShadow({ mode: 'open' });
// Add the template content to the shadow root.
this.shadowRoot.appendChild(template.content.cloneNode(true));
// Register element event listeners.
this.shadowRoot.querySelector('#back').addEventListener('click', () => Router.pop());
}
}
customElements.define('view-fade', ViewFade);Starter projects are available in the examples directory for the following frameworks:
The Route object contains the following properties:
| Property | Type | Description |
|---|---|---|
| name | string | The unique identifier for the route, must be the tag name of the web component if tag is not set. |
| tag | string | Optional, the registered custom-element tag name for your page web component, e.g. 'view-login'
|
| path | string | The relative URL path for the route to set in the browser navigation bar, e.g. '/login'
|
| title | string | The window title to show when the route is loaded, e.g. 'Login'
|
| animation | string | Optional, animation to apply when loading the route. Can be one of fade, slide, pop
|
| cache | boolean | Optional, indicator if the route template should be cached and reused, or recreated every time the route is navigated to. |
| load | function | Optional, function to execute before navigating to the route. Typically used to lazy load the page web component, e.g. () => import('./views/ViewLogin')
|
| guard | function | Optional, function to execute to check if a route may be navigated to. Typically used to limit access to routes., e.g. () => !this._isUserLoggedIn()
|
| isDefault | boolean | Optional, flag to set this route as the default route to load when the browser URL path is empty or default, e.g. /. Note: can only be applied to 1 route. |
| isFallback | boolean | Optional, flag to set this route as the fallback route to load when the user attempts to navigate to a route that does not exist, e.g. a 404 page. Note: can only be applied to 1 route. |
The router supports URL paths for the following patterns:
| Pattern | Example | Matches | Description |
|---|---|---|---|
| /part | /hello/world | /hello/world | A static path part, will be matched exactly. |
| /:param | /hello/:place | /hello/world | A required path parameter. |
| /:param? | /hello/:place? | /hello /hello/world |
An optional path parameter |
Note: Path part parameters must be valid URL characters including: Period (.), Dash (-), Characters (a-Z), Numbers (0-9).
The router styling can be customized using the following CSS Custom Properties:
| CSS Variable | Default Value | Description |
|---|---|---|
--omni-router-animation-duration |
300ms |
The duration it takes for route pages to be animated into view. |
--omni-router-animation-z-index |
1000000 |
The z-index to apply to the page being routed to. Set to a value higher than your app's highest z-index value to prevent elements from appearing above the page while routing. |
The <omni-router> tag dispatches the following events, that may be useful to subscribe to when wanting to apply changes to a page while a route is lazy loading, e.g. show a loading indicator.
| Event | Description |
|---|---|
| navigation-started | Fired before the route starts navigating, e.g. after guard is successful, but before load is called. |
| navigation-started | Fired after the route page has completely rendered on screen, e.g. after it was fully animated in. |
The <omni-router> tag provides the following functions:
| Function | Description |
|---|---|
clearCache(): void |
Clear the cache of route components. |
Full API documentation available here.
The Router class provides the following properties and functions:
| Property | Description |
|---|---|
get currentLocation(): RoutedLocation | undefined |
Get the currently location routed to. |
get previousLocation(): RoutedLocation | undefined |
Get the previous location routed to. |
get defaultRoute(): Route | undefined |
Get the route that should be rendered when navigating to the app base URL. |
get fallbackRoute(): Route | undefined |
Get the route that should be rendered when navigating to a route that does not exist. |
| Function | Description |
|---|---|
addEventListener(eventName: RouterEventType, callback: () => void): void |
Registers a callback function to be invoked when the router dispatches an event. |
removeEventListener(eventName: RouterEventType, callback: () => void): void |
Removes a callback function from the list of functions to be invoked when the router dispatches an event. |
addRoute(route: Route): void |
Add a route from the list of navigable routes. |
remove(name: string): void |
Remove a route from the list of navigable routes. |
getRouteForPath(pathOrUrl: string): Route | null |
Get the registered route for the given path. |
setDefault(name: string): boolean |
Set the route that should be rendered when navigating to the app base URL. |
setFallback(name: string): boolean |
Set the route that should be rendered when navigating to a route that does not exist. |
load(): Promise<boolean> |
Navigate to the current browser URL path. |
push(path: string, state = {}, animateOut = false): Promise<boolean> |
Push a new path onto the browser history stack and render it's registered route. |
replace(path: string, state = {}, animateOut = false): Promise<boolean> |
Update the current path in the browser history stack with a new path and render it's registered route. |
pop(delta?: number): Promise<boolean> |
Pops the current path in the browser history stack and navigate the previous path, or specified number pages back. |
popToPath(path: string, before = false): Promise<boolean> |
Pops back in history to a previous path, removing all paths after this point from the stack. |
Made possible by these fantastic people. 💖
See the CONTRIBUTING.md guide to get involved.
 jn42lm1 💻 📖 |
 BOTLANNER 💻 🔧 |
Licensed under MIT
We are hiring 🤝 Join us! 🇿🇦
https://www.capitecbank.co.za/about-us/careers