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 shim
• popstate Event

Copyright (c) 2022 Jason Mulligan Licensed under the BSD-3 license