history
history
is a JavaScript library that lets you easily manage session history anywhere JavaScript runs. history
abstracts away the differences in various environments and provides a minimal API that lets you manage the history stack, navigate, confirm navigation, and persist state between sessions.
Docs & Help
Installation
Using npm:
$ npm install --save history
Then with a module bundler like webpack, use as you would anything else:
import { createHistory } from 'history'
var createHistory = require('history').createHistory
The UMD build is also available on unpkg:
<script src="https://unpkg.com/history/umd/history.min.js"></script>
You can find the library on window.History
.
Usage
history
provides 3 different methods for creating a history
object, depending on your environment.
createBrowserHistory
is for use in modern web browsers that support the HTML5 history API (see cross-browser compatibility)createMemoryHistory
is used as a reference implementation and may also be used in non-DOM environments, like React NativecreateHashHistory
is for use in legacy web browsers
Depending on the method you want to use to keep track of history, you'll import
(or require
) one of these methods directly from the root directory (i.e. history/createBrowserHistory
). The remainder of this document uses the term createHistory
to refer to any of these implementations.
import createHistory from 'history/createBrowserHistory'
const history = createHistory()
const location = history.getCurrentLocation()
const unlisten = history.listen((location, action) => {
console.log(action, location.path, location.state)
})
history.push('/home', { some: 'state' })
unlisten()
Navigation
history
objects may be used programmatically change the current location
using the following methods:
push(path, state)
replace(path, state)
go(n)
goBack()
goForward()
The push
and replace
methods accept two arguments:
- The current URL
path
(including the query string and any hash fragment) - The location's state
The "location state" is an arbitrary object of data that may be tied to a particular location. In contrast to query parameters, this method of storing state keeps data out of the URL.
history.push('/home')
history.replace('/profile')
history.push('/about?the=query', { some: 'state' })
history.go(-1)
history.goBack()
Note: Location state is only supported in createBrowserHistory
and createMemoryHistory
.
Blocking Transitions
history
lets you register a prompt message that will be shown to the user before location listeners are notified. This allows you to make sure the user wants to leave the current page before they navigate away.
const unblock = history.block('Are you sure you want to leave this page?')
history.block(location => {
if (input.value !== '')
return 'Are you sure you want to leave this page?'
})
unblock()
Note: You'll need to provide a getUserConfirmation
function to use this feature with createMemoryHistory
(see below).
Customizing the Confirm Dialog
By default, window.confirm
is used to show prompt messages to the user. If you need to override this behavior (or if you're using createMemoryHistory
, which doesn't assume a DOM environment), provide a getUserConfirmation
function when you create your history object.
const history = createHistory({
getUserConfirmation(message, callback) {
}
})
Using a Base URL
If all the URLs in your app are relative to some other "base" URL, use the basename
option. This option transparently adds the given string to the front of all URLs you use.
const history = createHistory({
basename: '/the/base'
})
history.push('/home')
Note: This feature is not suppported in createMemoryHistory
.
Forcing Full Page Refreshes in createBrowserHistory
By default createBrowserHistory
uses HTML5 pushState
and replaceState
to prevent reloading the entire page from the server while navigating around. If instead you would like to reload as the URL changes, use the forceRefresh
option.
const history = createBrowserHistory({
forceRefresh: true
})
Modifying the Hash Type in createHashHistory
By default createHashHistory
uses a leading slash in hash-based URLs. You can use the hashType
option to use a different hash formatting.
const history = createHashHistory({
hashType: 'slash'
})
history.push('/home')
const history = createHashHistory({
hashType: 'noslash'
})
history.push('/home')
const history = createHashHistory({
hashType: 'hashbang'
})
history.push('/home')
Thanks
A big thank-you to Dan Shaw for letting us use the history
npm package name! Thanks Dan!
Also, thanks to BrowserStack for providing the infrastructure that allows us to run our build in real browsers.