Eleva Router is the official router plugin for Eleva.js, a minimalist, lightweight, pure vanilla JavaScript frontend runtime framework. This plugin adds flexible client-side routing capabilities to your Eleva.js applications by supporting multiple routing modes and by seamlessly integrating route information into your components.
Status: v1.0.2-alpha – This is an early alpha release. APIs may change until a stable release is announced.
- Eleva Router
Eleva Router extends Eleva.js with robust client-side routing functionality. It supports three routing modes:
- Hash-based Routing: Uses URL hash (e.g.
#/pageName). - Query-based Routing: Uses URL query parameters (e.g.
?page=pageName). - History-based Routing: Uses the History API for clean URLs (e.g.
/pageName).
The plugin automatically injects the current route information—such as path, query parameters, and full URL—directly into your component’s setup context as route. In addition, a navigate function is provided in the context so you can programmatically change routes from within your components.
- Multiple Routing Modes: Configure your routing strategy as
"hash","query", or"history". - Automatic Component Registration: If you provide routed components as definitions, the plugin automatically registers them with Eleva.js.
- Route Data Injection: The current route information is injected directly into the setup context as
route. - Built-in Navigation: Access a
navigatefunction within components to perform programmatic routing. - Default Route Fallback: Specify a
defaultRoutethat will be used if no route matches the current URL. - Seamless Eleva.js Integration: Designed to work out of the box with Eleva.js.
Install via npm:
npm install eleva-routerOr include it directly via CDN:
<!-- jsDelivr (Recommended) -->
<script src="https://cdn.jsdelivr.net/npm/eleva-router"></script>or
<!-- unpkg -->
<script src="https://unpkg.com/eleva-router/dist/eleva-router.min.js"></script>When installing the plugin via app.use(), you can pass a configuration object with the following options:
- mode (string): The routing mode. Options:
"hash"(default) – Useswindow.location.hash(e.g.#/pageName)."query"– Useswindow.location.searchand expects apagequery parameter (e.g.?page=pageName)."history"– Useswindow.location.pathnamewith the History API (e.g./pageName).
- routes (array): An array of route objects. Each route object should include:
- path (string): The URL path (e.g.
"/"or"/about"). - component (string or object): A globally registered component name or a component definition.
- props (object, optional): Additional props to pass to the routed component.
- path (string): The URL path (e.g.
- defaultRoute (object, optional): A route object to be used as a fallback when no matching route is found. It has the same structure as a route object.
Below is an example of how to set up Eleva Router with Eleva.js:
import Eleva from "eleva";
import ElevaRouter from "eleva-router";
const app = new Eleva("MyApp");
// Define routed components directly (no separate registration required)
const HomeComponent = {
setup: ({ route }) => {
console.log("Home route:", route.path);
return {};
},
template: () => `<div>Welcome Home!</div>`,
};
const AboutComponent = {
setup: ({ route, navigate }) => {
function goHome() {
navigate("/");
}
return { goHome };
},
template: (ctx) => `
<div>
<h1>About Us</h1>
<button @click="goHome">Go Home</button>
</div>
`,
};
const NotFoundComponent = {
setup: ({ route, navigate }) => ({
goHome: () => navigate("/"),
}),
template: (ctx) => `
<div>
<h1>404 - Not Found</h1>
<button @click="goHome">Return Home</button>
</div>
`,
};
// Install the router plugin with configuration options.
app.use(ElevaRouter, {
container: document.getElementById("app"),
mode: "history", // Options: "hash", "query", or "history"
routes: [
{ path: "/", component: HomeComponent },
{ path: "/about", component: AboutComponent },
],
defaultRoute: { path: "/404", component: NotFoundComponent },
});Within any routed component, the plugin injects a route object directly into the setup context. For example:
const MyComponent = {
setup: ({ route, navigate }) => {
console.log("Current path:", route.path);
console.log("Query parameters:", route.query);
console.log("Full URL:", route.fullUrl);
// Navigate programmatically if needed:
// navigate("/about");
return {};
},
template: (ctx) => `<div>Content here</div>`,
};- Within a Component:
Use thenavigatefunction provided in the context:navigate("/about");
- From Outside:
Call the router’snavigatemethod:app.router.navigate("/about");
new Router(eleva, options);- eleva: The Eleva.js instance.
- options: An object containing:
container(HTMLElement): The element where routed components are mounted.mode(string):"hash","query", or"history".routes(array): Array of route objects.defaultRoute(object, optional): A fallback route.
-
start()
Starts the router by listening to URL changes and resolving the initial route. -
routeChanged()
Extracts route details from the URL (based on the routing mode), parses query parameters, and mounts the corresponding component. -
navigate(path)
Programmatically navigates to the specified route, updating the URL accordingly. -
addRoute(route)
Dynamically adds a new route to the router. -
wrapComponentWithRoute(comp, routeInfo)
Wraps a component’s setup function to inject route data and a navigation function directly into the context.
- install(eleva, options)
Installs the router plugin, automatically registers routed components (if provided as objects), attaches a Router instance toeleva.router, and starts the router.
For further details on API usage, please refer to the full API documentation.
app.use(ElevaRouter, {
container: document.getElementById("app"),
mode: "history",
routes: [
{ path: "/", component: HomeComponent },
{ path: "/contact", component: ContactComponent },
],
defaultRoute: { path: "/404", component: NotFoundComponent },
});app.use(ElevaRouter, {
container: document.getElementById("app"),
mode: "query",
routes: [
{ path: "/", component: HomeComponent },
{ path: "/services", component: ServicesComponent },
],
});app.use(ElevaRouter, {
container: document.getElementById("app"),
mode: "hash",
routes: [
{ path: "/", component: HomeComponent },
{ path: "/about", component: AboutComponent },
],
});Q: What routing modes are supported?
A: You can choose between
"hash","query", and"history"modes via the plugin options.
Q: How do I define a default route?
A: Use the
defaultRouteoption in the plugin configuration to specify a fallback route if no match is found.
Q: How do I access route information within a component?
A: The
routeobject is injected directly into the setup context, and anavigatefunction is also provided.
Q: Can I add routes dynamically after initialization?
A: Yes, use the
addRoute(route)method on the router instance.
-
No Route Matches:
Verify that the URL matches one of your defined routes. If not, thedefaultRoute(if provided) will be used. -
Component Not Mounted:
Check that the container element provided in the configuration exists and is valid. -
Routing Mode Issues:
Ensure themodeoption is set to one of"hash","query", or"history". -
Navigation Not Working:
Confirm that you are calling thenavigate()function correctly from either the component context or viaapp.router.navigate().
Join our community for support, discussions, and collaboration:
- Contribution Guidelines Eleva Contribution Guidelines
- GitHub Discussions: For general questions or new ideas please start a discussion on Eleva Router Discussions
- GitHub Issues: Report bugs or request features on GitHub Issues
- Stack Overflow: For technical questions and support, please post your question on Stack Overflow using any of these tags eleva, eleva.js
This project is licensed under the MIT License.
Thank you for using Eleva Router! I hope this plugin makes building modern, client-side routed applications with Eleva.js a breeze.