Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

create-history

Lucifier129411MIT2.1.1TypeScript support: included

Manage browser history with JavaScript

history, location

readme

history Travis npm package

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:

// using an ES6 transpiler, like babel
import histrory from 'history'

history.createHistory()

// not using an ES6 transpiler
var createHistory = require('history').createHistory

The UMD build is also available on npmcdn:

<script src="https://npmcdn.com/history/dist/lib/index.js"></script>

You can find the library on window.History.

Basic Usage

A "history" encapsulates navigation between different screens in your app, and notifies listeners when the current screen changes.

import history from 'history'

const history = history.createHistory()

// Get the current location
const location = history.getCurrentLocation()

// Listen for changes to the current location
const unlisten = history.listen(location => {
  console.log(location.pathname)
})

// Push a new entry onto the history stack
history.push({
  pathname: '/the/path',
  search: '?a=query',

  // Extra location-specific state may be kept in session
  // storage instead of in the URL query string!
  state: { the: 'state' }
})

// When you're finished, stop the listener
unlisten()

You can find many more examples in the documentation!

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.

changelog

[HEAD]

  • Added hashType option to hash history for supporting different hash URL schemes including "hashbang" and no leading slash
  • Bugfix: Fix URL restoration on canceled popstate transitions

v3.0.0

May 30, 2016

  • location.query has no prototype
  • Warn about protocol-relative URLs (#243)
  • Bugfix: Ignore errors when saving hash history state if window.sessionStorage is undefined (#295)
  • Bugfix: Fix replacing hash path in IE served via file protocol (#126)

v3.0.0-2

Apr 19, 2016

  • Lower-cased UMD build file name

v3.0.0-1

Apr 19, 2016

  • Added locationsAreEqual to top-level exports
  • Breakage: Removed support for <base href> as basename (#94)
  • Removed dependency on deep-equal

3.0.0-0

Mar 19, 2016

  • Added history.getCurrentLocation() method
  • Breakage: history.listen no longer calls the callback synchronously once. Use history.getCurrentLocation instead
  • Breakage: location.key on the initial POP is null. Users who relied on this key may immediately use replace to get it back
  • Breakage: location.state is undefined (instead of null) if the location has no state. This helps us know when we need to access session storage and when we can safely ignore it
  • Bugfix: Hash history now uses a custom query string key/value pair only if the location has state. This obsoletes using { queryKey: false } to prevent the query string from being used (#163)
  • Bugfix: Do not access window.sessionStorage unless the location has state. This should minimize the # of times we access session storage and allow users to opt-out of using it entirely by not using location state

v2.0.0

Feb 4, 2016

  • Bugfix: Fix search base logic with an empty query (#221)
  • Bugfix: Fail gracefully when Safari 5 security settings prevent access to window.sessionStorage (#223)

v2.0.0-rc3

Feb 3, 2016

  • Bugfix: Don't convert same-path PUSH to REPLACE when location.state changes (#179)
  • Bugfix: Re-enable browser history on Chrome iOS (#208)
  • Bugfix: Properly support location descriptors in history.createLocation (#200)

v2.0.0-rc2

Jan 9, 2016

  • Add back deprecation warnings

v2.0.0-rc1

Jan 2, 2016

  • Bugfix: Don't create empty entries in session storage (#177)

v1.17.0

Dec 19, 2015

  • Bugfix: Don't throw in memory history when out of history entries (#170)
  • Bugfix: Fix the deprecation warnings on createPath and createHref (#189)

v1.16.0

Dec 10, 2015

  • Bugfix: Silence all warnings that were introduced since 1.13 (see reactjs/react-router#2682)
  • Deprecate the createLocation method in the top-level exports
  • Deprecate the state arg to history.createLocation

v1.15.0

Dec 7, 2015

  • Accept location descriptors in createPath and createHref (#173)
  • Deprecate the query arg to createPath and createHref in favor of using location descriptor objects (#173)

v1.14.0

Dec 6, 2015

  • Accept objects in history.push and history.replace (#141)
  • Deprecate history.pushState and history.replaceState in favor of passing objects to history.push and history.replace (#168)
  • Bugfix: Disable browser history on Chrome iOS (#146)
  • Bugfix: Do not convert same-path PUSH to REPLACE if the hash has changed (#167)
  • Add ES2015 module build (#152)
  • Use query-string module instead of qs to save on bytes (#121)

v1.13.1

Nov 13, 2015

  • Fail gracefully when Safari security settings prevent access to window.sessionStorage
  • Pushing the currently active path will result in a replace to not create additional browser history entries (#43)
  • Strip the protocol and domain from <base href> (#139)

v1.13.0

Oct 28, 2015

  • useBasename transparently handles trailing slashes (#108)
  • useBasename automatically uses the value of <base href> when no basename option is provided (#94)

v1.12.6

Oct 25, 2015

  • Add forceRefresh option to createBrowserHistory that forces full page refreshes even when the browser supports pushState (#95)

v1.12.5

Oct 11, 2015

  • Un-deprecate top-level createLocation method
  • Add ability to use { pathname, search, hash } object anywhere a path can be used
  • Fix useQueries handling of hashes (#93)

v1.12.4

Oct 9, 2015

  • Fix npm postinstall hook on Windows (#62)

v1.12.3

Oct 7, 2015

  • Fix listenBefore hooks not being called unless a listen hook was also registered (#71)
  • Add a warning when we cannot save state in Safari private mode (#42)

v1.12.2

Oct 6, 2015

v1.12.1

Oct 5, 2015

  • Give location objects a key by default
  • Deprecate history.setState

v1.12.0

Oct 4, 2015

  • Add history.createLocation instance method. This allows history enhancers such as useQueries to modify location objects when creating them directly
  • Deprecate createLocation method on top-level exports

v1.11.1

Sep 26, 2015

  • Fix location.basename when location matches exactly (#68)
  • Allow transitions to be interrupted by another

v1.11.0

Sep 24, 2015

  • Add useBasename history enhancer
  • Add history.listenBefore
  • Add history.listenBeforeUnload to useBeforeUnload history enhancer
  • Deprecate (un)registerTransitionHook
  • Deprecate (un)registerBeforeUnloadHook
  • Fix installing directly from git repo