{"id":22486745,"url":"https://github.com/ReactTraining/react-history","last_synced_at":"2025-08-02T19:32:58.616Z","repository":{"id":57333394,"uuid":"65757221","full_name":"ReactTraining/react-history","owner":"ReactTraining","description":"Manage session history with React","archived":false,"fork":false,"pushed_at":"2018-05-31T10:01:55.000Z","size":125,"stargazers_count":268,"open_issues_count":6,"forks_count":23,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-07-24T00:56:17.284Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ReactTraining.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-15T19:01:19.000Z","updated_at":"2025-01-07T11:37:09.000Z","dependencies_parsed_at":"2022-08-24T18:50:22.538Z","dependency_job_id":null,"html_url":"https://github.com/ReactTraining/react-history","commit_stats":null,"previous_names":["mjackson/react-history"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/ReactTraining/react-history","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReactTraining%2Freact-history","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReactTraining%2Freact-history/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReactTraining%2Freact-history/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReactTraining%2Freact-history/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ReactTraining","download_url":"https://codeload.github.com/ReactTraining/react-history/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReactTraining%2Freact-history/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268440854,"owners_count":24250899,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-06T17:15:18.456Z","updated_at":"2025-08-02T19:32:58.340Z","avatar_url":"https://github.com/ReactTraining.png","language":"JavaScript","readme":"# react-history [![Travis][build-badge]][build] [![npm package][npm-badge]][npm]\n\n[build-badge]: https://img.shields.io/travis/ReactTraining/react-history/master.svg?style=flat-square\n[build]: https://travis-ci.org/ReactTraining/react-history\n[npm-badge]: https://img.shields.io/npm/v/react-history.svg?style=flat-square\n[npm]: https://www.npmjs.com/package/react-history\n\n[`react-history`](https://www.npmjs.com/package/react-history) provides tools to manage session history using [React](https://facebook.github.io/react). It's a thin wrapper around the [`history`](https://www.npmjs.com/package/history) package. In web browsers, this library also transparently manages changes to the URL which makes it easier for creators of single-page applications to support things like bookmarks and the back button.\n\n**Note:** This library is highly experimental.\n\n## Installation\n\nUsing [npm](https://www.npmjs.com/):\n\n    $ npm install --save react-history\n\nThen with a module bundler like [webpack](https://webpack.github.io/), use as you would anything else:\n\n```js\n// using ES6 modules\nimport { BrowserHistory } from \"react-history\";\n\n// using CommonJS modules\nvar BrowserHistory = require(\"react-history\").BrowserHistory;\n```\n\nThe UMD build is also available on [unpkg](https://unpkg.com):\n\n```html\n\u003cscript src=\"https://unpkg.com/react-history/umd/react-history.min.js\"\u003e\u003c/script\u003e\n```\n\nYou can find the library on `window.ReactHistory`.\n\n## Usage\n\n`react-history` ships with 3 different history components that you can use depending on your environment.\n\n* `\u003cBrowserHistory\u003e` is for use in modern web browsers that support the [HTML5 history API](http://diveintohtml5.info/history.html) (see [cross-browser compatibility](http://caniuse.com/#feat=history))\n* `\u003cMemoryHistory\u003e` is used as a reference implementation and may also be used in non-DOM environments, like [React Native](https://facebook.github.io/react-native/)\n* `\u003cHashHistory\u003e` is for use in legacy web browsers\n\nDepending on the method you want to use to keep track of history, you'll `import` (or `require`) one of these methods directly from the package root (i.e. `history/BrowserHistory`). For the sake of brevity, the term `\u003cHistory\u003e` in this document refers to any of these implementations.\n\nBasic usage looks like this:\n\n```js\nimport History from \"react-history/BrowserHistory\";\n\nconst App = React.createClass({\n  render() {\n    return (\n      \u003cHistory\u003e\n        {({ history, action, location }) =\u003e (\n          \u003cp\u003e\n            The current URL is {location.pathname}\n            {location.search}\n            {location.hash}. You arrived at this URL via a {action} action.\n          \u003c/p\u003e\n        )}\n      \u003c/History\u003e\n    );\n  }\n});\n```\n\nThe props for each `\u003cHistory\u003e`, along with their default values are:\n\n```js\n\u003cBrowserHistory\n  basename=\"\"               // The base URL of the app (see below)\n  forceRefresh={false}      // Set true to force full page refreshes\n  keyLength={6}             // The length of location.key\n  // A function to use to confirm navigation with the user (see below)\n  getUserConfirmation={(message, callback) =\u003e callback(window.confirm(message))}\n/\u003e\n\n\u003cMemoryHistory\n  initialEntries={[ '/' ]}  // The initial URLs in the history stack\n  initialIndex={0}          // The starting index in the history stack\n  keyLength={6}             // The length of location.key\n  // A function to use to confirm navigation with the user. Required\n  // if you return string prompts from transition hooks (see below)\n  getUserConfirmation={null}\n/\u003e\n\n\u003cHashHistory\n  basename=\"\"               // The base URL of the app (see below)\n  hashType=\"slash\"          // The hash type to use (see below)\n  // A function to use to confirm navigation with the user (see below)\n  getUserConfirmation={(message, callback) =\u003e callback(window.confirm(message))}\n/\u003e\n```\n\n### Listening\n\n`\u003cHistory\u003e` elements call their `children` function every time the URL changes.\n\n```js\n\u003cHistory\u003e\n  {({ history, action, location }) =\u003e (\n    \u003cdiv\u003e\n      \u003cp\u003e\n        The current URL is {location.pathname}\n        {location.search}\n        {location.hash}.\n      \u003c/p\u003e\n      \u003cp\u003eYou arrived at this URL via a {action} action.\u003c/p\u003e\n    \u003c/div\u003e\n  )}\n\u003c/History\u003e\n```\n\nThe `history` object is the same object you'd get if you created your own [`history` object](https://npmjs.com/package/history) directly. Please refer to [the `history` docs](https://github.com/ReactTraining/history/blob/master/README.md) for more information on how to use it.\n\nThe `location` and `action` properties represent the current URL and how we got there.\n\n### Navigation\n\n`react-history` also provides the following components that may be used to modify the current URL:\n\n* `\u003cPush\u003e` pushes a new entry onto the history stack\n* `\u003cReplace\u003e` replaces the current entry on the history stack with a new one\n* `\u003cPop\u003e` modifies the current pointer or index into the history stack\n* `\u003cBack\u003e` moves back one entry in the history, shorthand for `\u003cPop go={-1}/\u003e`\n* `\u003cForward\u003e` moves forward one entry in the history, shorthand for `\u003cPop go={1}/\u003e`\n\nThese components are called \"action\" components because they modify the URL. When any of these are rendered, the URL updates and `\u003cHistory\u003e` objects emit a new location.\n\n`\u003cPush\u003e` and `\u003cReplace\u003e` accept either:\n\n* `path` and `state` props _or_\n* a `location` prop\n\n```js\n// Push a new entry onto the history stack.\n\u003cPush path=\"/home?the=query#the-hash\" state={{ some: 'state' }}/\u003e\n\n// Use a location-like object to push a new entry onto the stack.\n\u003cPush location={{\n  pathname: '/home',\n  search: '?the=query',\n  hash: '#the-hash'\n  state: { some: 'state' }\n}}/\u003e\n```\n\n**Note:** Location state is not supported using `\u003cHashHistory\u003e`.\n\nFor example, you could build a very simple `\u003cLink\u003e` component using a `\u003cPush\u003e`:\n\n```js\nimport React from \"react\";\nimport PropTypes from \"prop-types\";\nimport { Push } from \"react-history/Actions\";\n\nconst Link = React.createClass({\n  propTypes: {\n    to: PropTypes.string.isRequired\n  },\n\n  getInitialState() {\n    return { wasClicked: false };\n  },\n\n  render() {\n    const { to, ...props } = this.props;\n\n    // If the \u003cLink\u003e was clicked, update the URL!\n    if (this.state.wasClicked) return \u003cPush path={to} /\u003e;\n\n    return (\n      \u003cspan {...props} onClick={() =\u003e this.setState({ wasClicked: true })} /\u003e\n    );\n  }\n});\n```\n\n**Note:** This `\u003cLink\u003e` implementation is for demonstration purposes only. It is not accessible and does not include many of the nice features of a real hyperlink. If you're looking for a proper `\u003cLink\u003e` implementation, [please use `react-router`](https://www.npmjs.com/package/react-router).\n\n### Blocking Transitions\n\n`react-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. You do this by rendering a `\u003cPrompt\u003e` component.\n\n```js\nimport Prompt from \"react-history/Prompt\";\n\nconst Form = React.createClass({\n  getInitialState() {\n    return { inputText: \"\" };\n  },\n\n  handleChange(event) {\n    this.setState({ inputText: event.target.value });\n  },\n\n  render() {\n    const { inputText } = this.state;\n\n    return (\n      \u003cform\u003e\n        \u003cPrompt\n          message=\"Are you sure you want to leave before submitting the form?\"\n          when={inputText}\n        /\u003e\n        \u003cinput\n          type=\"text\"\n          defaultValue={inputText}\n          onChange={this.handleChange}\n        /\u003e\n      \u003c/form\u003e\n    );\n  }\n});\n```\n\n**Note:** You'll need to provide a `getUserConfirmation` prop to use `\u003cPrompt\u003e`s with `\u003cMemoryHistory\u003e` (see [the `history` docs](https://github.com/ReactTraining/history#customizing-the-confirm-dialog)).\n\n### Using a Base URL\n\nIf 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.\n\n```js\n// All URLs transparently have the \"/the/base\" prefix.\n\u003cHistory basename=\"/the/base\"\u003e\n  {({ location }) =\u003e (\n    // When the URL is /the/base/home, location.pathname is just /home.\n    \u003cp\u003eThe current pathname is {location.pathname}.\u003c/p\u003e\n  )}\n\u003c/History\u003e\n```\n\n**Note:** `basename` is not suppported in `\u003cMemoryHistory\u003e` where you have full control over all your URLs.\n\n### Forcing Full Page Refreshes in `\u003cBrowserHistory\u003e`\n\nBy default `\u003cBrowserHistory\u003e` 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.\n\n```js\n\u003cBrowserHistory forceRefresh /\u003e\n```\n\n### Modifying the Hash Type in `\u003cHashHistory\u003e`\n\nBy default `\u003cHashHistory\u003e` uses a leading slash in hash-based URLs. You can use the `hashType` option to use a different hash formatting.\n\n```js\n// The default is to add a leading / to all hashes, so your URLs\n// are like /#/inbox/5. This is also know as the \"slash\" hash type.\n\u003cHashHistory hashType=\"slash\"/\u003e\n\n// You can also omit the leading slash using the \"noslash\" hash type.\n// This gives you URLs like /#inbox/5.\n\u003cHashHistory hashType=\"noslash\"/\u003e\n\n// Support for Google's legacy AJAX URL \"hashbang\" format gives you\n// URLs like /#!/inbox/5.\n\u003cHashHistory hashType=\"hashbang\"/\u003e\n```\n\n## Thanks\n\nThanks to [BrowserStack](https://www.browserstack.com/) for providing the infrastructure that allows us to run our build in real browsers.\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FReactTraining%2Freact-history","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FReactTraining%2Freact-history","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FReactTraining%2Freact-history/lists"}