Single-page-application router.
Installs a global listener for all clicks on <a href="...">
.
Install
Install via rhud
using your favorite package manager.
Includes TS types.
Usage
At its simplest, use like so:
; ;
This example will be called for every route (not those with "." in the URL, except ending with ".html").
Options
You can configure not to be called immediately, and control which URLs are matched:
Context
The listener you configure is passed an object of type RouterContext
.
This contains the requested href
, as well as:
isNavigation
: is this a navigation (e.g., click on link) or is it due to a back/forward history eventfirstRun
: is this the first run (isNavigation
will be false)signal
: anAbortSignal
that will be aborted if another route starts before this is completestate
: the current or futurewindow.history.state
- the
ready()
method: call when you're happy for the URL to change
Navigation Mode
In navigation mode, say, the user clicking on a page link, the URL hasn't changed when the listener method is invoked. Here's an example:
;
If you're not in navigation mode, this means the user has hit back or forward to change the URL. In this case, the URL has already changed when the method opens. You should aim to update the DOM without doing any asynchronous calls, as the History API's default behavior is to scroll to the page after a frame.
;
There are mitigation strategies if back/forward requires a network request to display properly. You can save the scroll position when the listener runs, reset it after a frame, and then scroll to the intended position later.
Requirements
Uses Promise
(but not async
or await
), so probably works on modern browsers.
This includes a tiny AbortSignal
and AbortController
polyfill (as these are still fairly modern as of 2020).