Imagine you didn't have to write a bunch of JavaScript to get a slick, progressively enhanced interface! dom-router
is a URL hash to DOM router which automatically, & intelligently toggles visibility of Elements
based on popstate
events.
This provides a clean separation of concerns, and progressive enhancement in a simple library. You can write clean HTML,
and dom-router
will progressively enhance the interface with CSS classes (not supplied). DOM updates happen on an
animation frame to minimize impacting your application. An optional callback
allows you to handle application
state changes the way you want.
This example is meant to demonstrate multi-tier routing in a single page application. When the HTML is "clean", it is
functional for screen readers & text based browsers like lynx
, and with progressive enhancement, developers can add
new behaviour without impacting the experience of other consumers.
import {router} from "./dom-router.js";
window.appRouter = router({callback: arg => console.log(`${arg.element.id} is visible`)});
<nav>
<ul>
<li><a href="#main">Main</a></li>
<li><a href="#settings/billing" class="settings">Billing</a></li>
<li><a href="#settings/password" class="settings">Password</a></li>
<li><a href="#settings/avatar" class="settings">Avatar</a></li>
</ul>
</nav>
...
<article>
<section id="main">...</section>
<section id="settings">
<section id="billing">...</section>
<section id="password">...</section>
<section id="avatar">...</section>
</section>
</article>
This would be the result if a user visited #settings/billing
:
<nav>
<ul>
<li><a href="#main">Main</a></li>
<li><a href="#settings/billing" class="settings dr-current">Billing</a></li>
<li><a href="#settings/password" class="settings">Password</a></li>
<li><a href="#settings/avatar" class="settings">Avatar</a></li>
</ul>
</nav>
...
<article>
<section id="main" class="dr-hidden">...</section>
<section id="settings">
<section id="billing">...</section>
<section id="password" class="dr-hidden">...</section>
<section id="avatar" class="dr-hidden">...</section>
</section>
</article>
When loaded with a script tag, window.domRouter.router()
will be created.
Boolean
which enables/disables routing
Function to execute after route has changed, takes arg
which describes the event
Object
with current
, & hidden
keys which have corresponding CSS class values, defaults to "dr-current", & "dr-hidden"
Context for DOM selector, defaults to body
if not specified
Multi-tier routing delimiter, defaults to /
, e.g. #settings/billing
; each tier should map to a nested id
Boolean
which logs routing to router.history[]
if true
, defaults to false
; could be a memory leak if logging is enabled and target Elements
are removed from DOM
[Optional] The starting route to display if one is not specified, or an invalid route is specified
Boolean
which enables/disables remaining at Y position
when the route changes, i.e. no scrolling, defaults to true
.
Boolean
which enables/disables sticky routing, defaults to true
.
Boolean
which enables/disables sticky searchParams
of location
, defaults to false
. When it disabled history.replaceState()
is executed on location
before callback()
.
String
Storage used for stickyRoute
, defaults to session
; valid options are session
or local
.
String
Key for persistent storage for stickyRoute
.
Returns the current Route
; if logging is enabled the trigger Element
will be present
Event handler
Scans ctx
for routes & resets default
which is an optional argument, otherwise it defaults to the first route
Context specific DOM selector
Element.classList
API, or shimpopstate
EventCopyright (c) 2022 Jason Mulligan Licensed under the BSD-3 license