LICENSE | ||
README.md | ||
story.js |
story
Minimal HTML5 history API wrapper
About
The purpose of this library was to create a very thin wrapper around the HTML5 history API, but still one that handles the basic everyday tasks. It started as a bit of shared code that I found myself using on a couple of personal projects, so I decided to publish it here.
It handles programmatically switching to a URL or replacing a URL, informing your code when the URL changes, and intercepting clicks on hyperlinks to call the history API instead of performing page navigation.
What it is not
It is not an actual router. You provide a function, this library calls your function when the URL changes. That's it.
How to use
This is an ES2015 module. You will need some way to bundle and transpile this for your app.
Methods available
setBase(base)
Set a new value for the base path. Defaults to "/"
. This should be the root path of your app.
watch(cb)
Register a new callback to be informed whenever the path changes. Your callback will be called with one argument, the portion of the path after the currently specified base.
unwatch(cb)
Unregisters a previously registered watcher.
to(url)
Perform (virtual) navigation to the new URL. url
will be appended to the current base.
Also calls any currently registered watchers.
replace(url)
Replace the current URL with the new one you specify. url
will be appended to the current base. Call this when you want to, for example, perform a redirect without creating a new entry in the navigation history.
Also calls any currently registered watchers.
Hyperlink handling
Activating hyperlinks will be replaced with a call to to()
provided that:
- the control/meta/shift keys were not pressed during the click, and the click was not done with the middle mouse button
- the hyperlink element has no
target
value - the hyperlink's
href
begins with the currently selected base - defaults to"/"
and can be changed withsetBase()
If you have a hyperlink that would otherwise be caught by the click handler and you do not want it to be, you can specify target="_self"
on the link element.
License
This code was written by Conduitry and is released into the public domain.