Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/capitec/omni-router
Framework agnostic, zero dependency, client-side web component router.
https://github.com/capitec/omni-router
router single-page-app spa-router vanilla-js
Last synced: about 1 month ago
JSON representation
Framework agnostic, zero dependency, client-side web component router.
- Host: GitHub
- URL: https://github.com/capitec/omni-router
- Owner: capitec
- License: mit
- Created: 2022-12-08T07:50:48.000Z (about 2 years ago)
- Default Branch: develop
- Last Pushed: 2024-08-26T09:32:34.000Z (4 months ago)
- Last Synced: 2024-08-31T00:50:44.809Z (4 months ago)
- Topics: router, single-page-app, spa-router, vanilla-js
- Language: TypeScript
- Homepage: https://capitec.github.io/open-source/docs/omni-router/
- Size: 909 KB
- Stars: 15
- Watchers: 2
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
Omni Router
@capitec/omni-router
Framework agnostic, zero dependency, client-side web component router
[Introduction]
[Usage]
[API Reference]
[Contributors]
[License]
---
## Introduction
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](https://developer.mozilla.org/en-US/docs/Web/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.
## Usage
1️⃣ Install the library in your project.
```bash
npm install @capitec/omni-router
```
2️⃣ Specify a base href location in your `index.html` to use as root for page navigation.
```html
```
3️⃣ Import the ```Router``` package.
```js
// JS import
import '@capitec/omni-router';
// or HTML import
```
4️⃣ Place the `` tag in your web page, all routes will be rendered in this container.
```html
```
5️⃣ Define the pages you will route to.
```js
// 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();
```
### 💡 Example
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.
```html
Omni Router Demo
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();
```
```js
// 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 = `
:host {
.background-color: white;
}
Hello World
⬅ Go Back
`;
// 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);
```
### 🚩 Framework Starter Projects
Starter projects are available in the [examples directory](./examples) for the following frameworks:
## API Reference
### Route Object
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. |
### Path Patterns
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).
### Styling
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. |
### Router Tag
The `````` 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 `````` tag provides the following functions:
| Function | Description |
| -------- | ----------- |
| ```clearCache(): void``` | Clear the cache of route components. |
### Router Class
Full API documentation [available here](https://capitec.github.io/open-source/?repo=Omni-Router).
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``` | Navigate to the current browser URL path. |
| ```push(path: string, state = {}, animateOut = false): Promise``` | Push a new path onto the browser history stack and render it's registered route. |
| ```replace(path: string, state = {}, animateOut = false): Promise``` | Update the current path in the browser history stack with a new path and render it's registered route. |
| ```pop(delta?: number): Promise``` | 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``` | Pops back in history to a previous path, removing all paths after this point from the stack. |
## Contributors
Made possible by these fantastic people. 💖
See the [`CONTRIBUTING.md`](./CONTRIBUTING.md) guide to get involved.
## License
Licensed under [MIT](LICENSE)
We are hiring 🤝 Join us! 🇿🇦
https://www.capitecbank.co.za/about-us/careers
