{"id":22454374,"url":"https://github.com/elementumjs/router","last_synced_at":"2025-10-28T13:08:34.478Z","repository":{"id":57111108,"uuid":"423447345","full_name":"elementumjs/router","owner":"elementumjs","description":"Very basic HTML5 History router implementation for SPA apps.","archived":false,"fork":false,"pushed_at":"2021-11-01T16:48:42.000Z","size":382,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-22T09:26:31.153Z","etag":null,"topics":["javascript","javascript-library","router","spa-router","typescript","webcomponents"],"latest_commit_sha":null,"homepage":"https://elementumjs.github.io/router/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elementumjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-01T11:55:13.000Z","updated_at":"2021-11-02T10:45:59.000Z","dependencies_parsed_at":"2022-08-20T19:20:46.520Z","dependency_job_id":null,"html_url":"https://github.com/elementumjs/router","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/elementumjs/router","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elementumjs%2Frouter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elementumjs%2Frouter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elementumjs%2Frouter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elementumjs%2Frouter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elementumjs","download_url":"https://codeload.github.com/elementumjs/router/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elementumjs%2Frouter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261475950,"owners_count":23164074,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","javascript-library","router","spa-router","typescript","webcomponents"],"created_at":"2024-12-06T07:07:32.054Z","updated_at":"2025-10-28T13:08:29.448Z","avatar_url":"https://github.com/elementumjs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://raw.githubusercontent.com/elementumjs/router/main/assets/header.svg\"/\u003e\n\n[![CDN](https://img.shields.io/badge/CDN-jsDelivr-blueviolet)][1]\n[![package_version](https://img.shields.io/npm/v/@elementumjs/router)][2]\n[![production](https://github.com/elementumjs/router/workflows/production/badge.svg)][3]\n[![reference](https://img.shields.io/badge/docs-REFERENCE-blue)][4]\n[![license](https://img.shields.io/github/license/elementumjs/router)][5]\n\n`@elementumjs/router` is a very basic HTML5 History router implementation for SPA apps.\n\n- [📝 How to use it][6]\n    - [Route definition][7]\n    - [Router initialization][8]\n    - [Navigate between routes][9]\n- [🧪 Full example][10]\n- [⚙️ Installation][11]\n    - [Import from CDN as ES Module][12]\n    - [Or install the package locally][13]\n    - [Other import methods][14]\n\n---\n\n\u003cimg src=\"https://raw.githubusercontent.com/elementumjs/router/main/assets/how-to-use-it.svg\"/\u003e\n\n## How to use it\n\n### Route definition\n\nAny route must have two properties at least: `path` and `view`.\n  * **`route.path`** property contains the URI string definition for this route (the part of the URL that is after the hash character `#`). \n  * **`route.view`** property contains the root route element definition, and it can be defined as a string, that represents the element tagName to be created, or as a HTMLElement, that contains the raw element. \n\nThe routes have also another two optional properties:\n  * **`route.title`** that is used to update the `document.title` when a transition occurs. \n  * **`route.handler`** property contains a function to be called when a transition occurs.\n\nExample of routes definition:\n```javascript\nconst aboutView = document.createElement('div');\n// ...\nconst routes = [\n    {\n        path: '/', \n        title: 'Home | My personal site', \n        view: 'my-homepage' // Set the route view as string tagName\n    },\n    {\n        path: '/about', \n        title: 'About | My personal site', \n        view: aboutView, // Set the route view as HTMLElement instance\n        handler: () =\u003e {\n            // Get route transition data\n            console.log('[About View handler]', window.history.state);\n        } \n    }\n];\n```\n\n### Router initialization\n\nTo initialize the router, is required to define a root HTMLElement (`target`) to use as route container and a correct routes definition (check the previous section). \n\nExample of router initialization:\n```javascript\nimport Router from '@elementumjs/router';\n\nconst routes = [ /** ... */ ];\nconst target = document.querySelector('container');\n\n// Basic router initialization\nconst router = Router(target, routes);\n```\n\nTo use the router instance across the app, it will be defined as global object into the `window` instance:\n```javascript\nimport Router from '@elementumjs/router';\n\nconst routes = [ /** ... */ ];\nconst target = document.querySelector('container');\n\n// Global router initialization\nwindow['router'] = Router(target, routes);\n```\n\n### Navigate between routes\n\nThe navigation is possible with two ways, with HTML anchors or programmatically. The programmatically way allows to send some data to the following view.\n\n| Method | Example |\n|:---|:---|\n| HTML anchor | `\u003ca href=\"#/about\"\u003eAbout me\u003c/a\u003e` |\n| Programmatically | `window.router.go('/home', { param1: 'value1' });` |\n\n\n\u003cimg src=\"https://raw.githubusercontent.com/elementumjs/router/main/assets/full-example.svg\"/\u003e\n\n## Full example\n\n\u003cimg src=\"https://raw.githubusercontent.com/elementumjs/router/main/assets/demo.gif\" width=\"600\"/\u003e\n\nWebApp entry point `app.js`;\n\n```javascript\nimport Router from '@elementumjs/router';\nimport './my-homepage.js';\n\nconst aboutView = document.createElement('div');\naboutView.innerHTML = `\n    \u003ch1\u003eIt's me!\u003c/h1\u003e\n    \u003cp\u003eLorem ipsum dolor sit amet, consectetur adipiscing elit. Nam bibendum tortor id nisl mollis fermentum. Curabitur nec tellus nisl. Sed placerat aliquet auctor. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Curabitur sed posuere odio.\u003c/p\u003e\n    \u003cbutton\u003eGo home\u003c/button\u003e\n`;\n\n// Go to Home programmatically\naboutView.lastElementChild.onclick = () =\u003e window.router.go('/', { param1: 'value1' });\n\n// Get target defined on index.html\nconst target = document.querySelector('container');\nconst routes = [\n    {\n        path: '/', \n        title: 'Home | My personal site', \n        view: 'my-homepage' \n    },\n    {\n        path: '/about', \n        title: 'About | My personal site', \n        view: aboutView, \n        handler: () =\u003e {\n            // Get route transition data\n            console.log('[About View handler]', window.history.state);\n        } \n    }\n];\n\n// Make router instance available globally\nwindow['router'] = Router(target, routes);\n```\n\nHome page component definition: `my-homepage.js`.\n\n```javascript\nimport { Component, html } from '@elementumjs/component';\n\nComponent.attach('my-homepage', class extends Component {\n    template() {\n        return html`\u003cdiv\u003e\n            \u003ch1\u003e${ 'Hello to my web!' }\u003c/h1\u003e\n            \u003ca href=\"#/about\"\u003eKnow more about me\u003c/a\u003e\n        \u003c/div\u003e`;\n    }\n\n    created() {\n        // Get route transition data\n        console.log('[Home View created]', window.history.state);\n    }\n});\n```\n\n`index.html` definition:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\t\u003cbody\u003e\n\t\t\u003ccontainer\u003e\u003c/container\u003e\n\t\t\n\t\t\u003cscript type=\"module\" src=\"./app.js\"\u003e\u003c/script\u003e\n\t\u003c/body\u003e\n\u003c/html\u003e\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/elementumjs/router/main/assets/installation.svg\"/\u003e\n\n## Installation\n\n### Import from CDN as ES Module\n\nImport from [jsDelivr CDN](https://www.jsdelivr.com/):\n\n```javascript\n    import Router from \"https://cdn.jsdelivr.net/gh/elementumjs/router/dist/router.esm.js\";\n```\n\n### Or install the package locally\n\n#### Download the package\n\nInstall via `npm`:\n\n```sh\n    npm install @elementumjs/router\n```\n\n#### Import as ES Module\n\n[ES Module](http://exploringjs.com/es6/ch_modules.html) builds are intended for use with modern bundlers like [webpack 2](https://webpack.js.org) or [rollup](http://rollupjs.org/). Use it with ES6 JavaScript `import`:\n  \n```javascript\n    import Router from '@elementumjs/router';\n```\n\n### Other import methods\n\nCheckout other import methods in [`dist/README.md`](./dist/README.md).\n\n[1]: https://cdn.jsdelivr.net/gh/elementumjs/router/dist/router.umd.js\n\n[2]: https://www.npmjs.com/package/@elementumjs/router\n\n[3]: https://github.com/elementumjs/router/actions?query=workflow%3Aproduction\n\n[4]: docs/modules.md\n\n[5]: ./LICENSE\n\n[6]: #how-to-use-it\n\n[7]: #route-definition\n\n[8]: #router-initialization\n\n[9]: #navigate-between-routes\n\n[10]: #full-example\n\n[11]: #installation\n\n[12]: #import-from-cdn-as-es.module\n\n[13]: #or-install-the-package-locally\n\n[14]: #other-import-methods","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felementumjs%2Frouter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felementumjs%2Frouter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felementumjs%2Frouter/lists"}