history abstracts away the differences in these different platforms and provides a minimal API that lets you manage the history stack, navigate, confirm navigation, and persist state between sessions.
$ npm install history
The first thing you'll need to do is create a history object.
history provides several different
create* methods that you can use depending on your environment.
createHistoryis for use in modern web browsers that support the HTML5 history API
createHashHistoryis for use in legacy web browsers (see caniuse for compatibility)
createMemoryHistoryis used mainly for testing and does not persist across sessions
Once you get a
history object, use
history.listen to be notified when the
import createHistory from 'history';var history = createHistory;// Listen for changes to the current location. The// listener is called once immediately.var unlisten = historylistenconsole.loglocationpathname;;// When you're finished, stop the listener.unlisten;
location object is conceptually similar to
document.location in web browsers, with a few extra goodies.
location objects have the following properties:
pathname The pathname portion of the URL, without query stringsearch The query string portion of the URL, including the ?state An object of data tied to this locationaction One of PUSH, REPLACE, or POPkey A unique identifier for this location
If you'd like, you can create a
location object programmatically using
import createLocation from 'history';var location = createLocation'/a/path?a=query' some: 'state' ;
You can also use a
history object to programmatically change the current
location using the following methods:
path argument to
replaceState represents a complete URL path, including the query string. The
state argument should be a JSON-serializable object.
// Push a new entry onto the history stack.historypushState some: 'state' '/home';// Replace the current entry on the history stack.historyreplaceState some: 'other state' '/profile';// Go back to the previous history entry. The following// two lines are synonymous.historygo-1;historygoBack;
Sometimes you may want to prevent the user from going to a different page. For example, if they are halfway finished filling out a long form, and they click the back button (or try to close the tab), you may want to prompt them to confirm they actually want to leave the page before they lose the information they've already entered. For these cases,
history lets you register transition hooks that return a prompt message you can show the user before the location changes. For example, you could do something like this:
historyregisterTransitionHookif inputvalue !== ''return 'Are you sure you want to leave this page?';;
You can dynamically add/remove transition hooks using
unregisterTransitionHook as well.
window.confirm by default to display confirmation messages to users. However, you can provide your own custom confirmation dialog box using the
getUserConfirmation hook when you create your
var history = createHistorycallbackwindowconfirmmessage; // The default;
window.location.hash is a common trick that is used to mimic the HTML5 history API in older browsers. It works for most use cases and provides good compatibility across a wide range of browsers. However, in order to preserve state across browser sessions we need a place to store some state. HTML5 gives us the
pushState method and the
popstate event, but in older browsers the only thing we have is the URL. So, when using hash history, you'll see an extra item in your query string that looks something like
_k=123abc. This is a key that
history uses to look up persistent state data in
window.sessionStorage between page loads. If you prefer to use a different query parameter, or to opt-out of this behavior entirely, use the
queryKey configuration option.
// Use _key instead of _k.var history = createHashHistoryqueryKey: '_key';// Opt-out of persistent state, not recommended.var history = createHashHistoryqueryKey: false;
One other thing to keep in mind when using hash history is that you cannot also use
window.location.hash as it was originally intended, to link an anchor point within your HTML document.
A big thank-you to Dan Shaw for letting us use the
history npm package name! Thanks Dan!