{"id":13835333,"url":"https://github.com/fi3ework/react-live-route","last_synced_at":"2025-04-06T09:09:47.981Z","repository":{"id":32644525,"uuid":"138316485","full_name":"fi3ework/react-live-route","owner":"fi3ework","description":":pushpin: An enhanced react-router-v4/5 Route that keeps route alive.","archived":false,"fork":false,"pushed_at":"2023-01-01T09:16:16.000Z","size":719,"stargazers_count":218,"open_issues_count":6,"forks_count":20,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-23T18:14:11.730Z","etag":null,"topics":["keep-alive","react","react-router","react-router-v4","router"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fi3ework.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-22T15:06:56.000Z","updated_at":"2024-03-17T12:05:35.000Z","dependencies_parsed_at":"2023-01-14T22:00:17.081Z","dependency_job_id":null,"html_url":"https://github.com/fi3ework/react-live-route","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fi3ework%2Freact-live-route","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fi3ework%2Freact-live-route/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fi3ework%2Freact-live-route/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fi3ework%2Freact-live-route/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fi3ework","download_url":"https://codeload.github.com/fi3ework/react-live-route/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247457803,"owners_count":20941906,"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","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":["keep-alive","react","react-router","react-router-v4","router"],"created_at":"2024-08-04T14:00:59.683Z","updated_at":"2025-04-06T09:09:47.955Z","avatar_url":"https://github.com/fi3ework.png","language":"TypeScript","funding_links":[],"categories":["目录"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ch1 align=\"center\"\u003ereact-live-route\u003c/h1\u003e\n    \u003cp align=\"center\"\u003e\n        An enhanced version of react-router-v4 Route Component that keeps route component alive on unmatched path and restore it completely on match path.\n    \u003cp\u003e\n    \u003cp align=\"center\"\u003e\n        \u003ci\u003e\n            \u003ca href=\"https://www.npmjs.com/package/react-live-route\"\u003e\n              \u003cimg src=\"https://img.shields.io/npm/v/react-live-route.svg?color=%2361AFEF\" alt=\"NPM Version\"\u003e\n            \u003c/a\u003e\n            \u003ca href=\"https://circleci.com/gh/fi3ework/react-live-route\"\u003e\n              \u003cimg src=\"https://img.shields.io/circleci/project/github/fi3ework/react-live-route/master.svg?style=flat-square\" alt=\"Build Status\"\u003e\n            \u003c/a\u003e\n\u003ca href='https://coveralls.io/github/fi3ework/react-live-route'\u003e\u003cimg src='https://img.shields.io/coveralls/github/fi3ework/react-live-route/master.svg?style=flat-square' alt='Coverage Status' /\u003e\u003c/a\u003e\n        \u003c/i\u003e\n    \u003c/p\u003e\n\u003c/p\u003e\n\n## Document\n\n[中文](./docs/README-zh.md)\n\n## Feedback\n\nFeel free to open an [issue](https://github.com/fi3ework/react-live-route/issues/new) to ask for help or have a discussion. If there is a detailed code problem help is needed, please fork [this](https://codesandbox.io/s/20pm25081r) minimal demo to provide a reproduce scenario, or your issue might be closed directly due to lack of information.\n\n## Demo\n\n### codeSandbox\n\nYou can experience and review the source code on codeSandbox.\n\n[![Edit react-live-route-demo-1](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/yj9j33pw4j)\n\n### QR code\n\nYou also can scan the QR code of the demo above to experience it on mobile device.\n\n![qr](./docs/qr.png)\n\n## Install\n\n```bash\nnpm install react-live-route\n```\n\nor\n\n```bash\nyarn add react-live-route\n```\n\n## About\n\nIt will hide component of route instead of unmout it when the path is not match and restore it when come back. There are a few APIs provided to control the hidden condition of component.\n\nExample：\n\nThere is a item list page, click on the items on this page will enter the item detail page. When entering the detail page, item list page will be hidden and it will keep hidden when you are on item detail page. Once back to the list page, the list page will be restored to the last state of leaving.\n\n## Features\n\n- ✅ Fully compatible with react-router-v4, all passed the react-router-v4 unit tests.\n- 🎯 Completely restored to the state of the last time you left (scroll position included).\n- 🔒 Minimally invasive, all you need to do is import LiveRoute.\n- ✌️ Super easy API.\n\n## Hint\n\n- **Using with \u003cSwitch /\u003e, see [Use in `\u003cSwitch\u003e`](#Use in `\u003cSwitch\u003e`) for detail.**\n- **Using with code splitting, see [ensureDidMount](#ensureDidMount (code-splitting)) for detail.**\n- If LiveRoute's parent route is unmounted on current location, then it will also be unmounted . This is determined by the top-down design principle of React. You can use LiveRoute to declares a parent route to solve this problem or stop nestting the router.\n- In some cases the DOM of LiveRoute will be modified directly and the scroll position will not change when navigation. This is not a problem with react-live-route. You can scroll the screen to the top manually and you may get some help from [this article](https://github.com/ReactTraining/react-router/blob/2b94b8f9e115bec6426be06b309b6963f4a96004/packages/react-router-dom/docs/guides/scroll-restoration.md) from react-router. By the way, if the scroll position will be restored by LiveRoute, it will come up after the scroll operation in componet of LiveRoute due to the render order of React.\n\n## Usage\n\n### 1. Enhance Route with withRouter\n\nThe class imported from `react-live-route` **must** be wrapped by `withRouter` to touch the property of context to work as expected.\n\n```jsx\nimport NotLiveRoute from 'react-live-route'\nimport { withRouter } from 'react-router-dom'\n\nconst LiveRoute = withRouter(NotLiveRoute)\n```\n\n### 2. Props of LiveRoute\n\n#### livePath: (string | string[])\n\n`livePath` is the path you want to hide the component instead of unmount it. The specific rules of `livePath` are the same as `path` props of Route in react-router-v4. You still can use `component` or `render` props to render a component.\n\n`livePath` also can accept an array of string above since 1.2.0. `livePath` is matched if any string in the array is matched.\n\nLiveRoute will re-render when it come back from a `path` matching location from the `livePath` matching location. It will unmount on other unmatched locations.\n\nExample:\n\nThe route of List will be rendered normally under `/list`, and it will be hidden when location change to `/user/:id`, and it will be unmounted normally when entering other locations.\n\n```tsx\nimport NotLiveRoute from 'react-live-route'\nimport { withRouter } from 'react-router-dom'\n\nconst LiveRoute = withRouter(NotLiveRoute)\n\n\u003cLiveRoute path=\"/list\" livePath=\"/user/:id\" component={List} /\u003e\n```\n\n#### alwaysLive: boolean\n\n`alwaysLive` is just like `livePath`. The difference is the component will not be unmount on **any other location** after the it's first mount.\n\nExample:\n\nAfter the first mount on match location, the Modal page will be hidden when the path is not matched, and will re-render when `path` match again.\n\n```jsx\nimport NotLiveRoute from 'react-live-route'\nimport { withRouter } from 'react-router-dom'\n\nconst LiveRoute = withRouter(NotLiveRoute)\n\n\u003cLiveRoute path=\"/list\" alwaysLive={true} component={Modal} /\u003e\n```\n\n#### onHide: (location, match, history, livePath, alwaysLive) =\u003e void\n\nThis hook will be triggered when LiveRoute will hide in `componentWillReceiveProps` stage (so it happens before re-render).\n\nExample of usage is below.\n\n#### onReappear: (location, match, history, livePath, alwaysLive) =\u003e void\n\nThis hook will be triggered when LiveRoute will reappear from hide in `componentWillReceiveProps` stage (so it happens before re-render).\n\n```js\nimport NotLiveRoute from 'react-live-route'\nimport { withRouter } from 'react-router-dom'\n\nconst LiveRoute = withRouter(NotLiveRoute)\n\n\u003cLiveRoute\n  path=\"/items\"\n  component={List}\n  livePath=\"/item/:id\"\n  name=\"items\"\n  onHide={(location, match, livePath, alwaysLive) =\u003e {\n    console.log('[on hide]')\n  }}\n  onReappear={(location, match, livePath, alwaysLive) =\u003e {\n    console.log('[on reappear]')\n    console.log(routeState)\n  }}\n/\u003e\n```\n\n#### forceUnmount: (location, match, history, livePath, alwaysLive) =\u003e boolean\n\nforceUnmount is funtion that return a boolean value to decide weather to forceUnmount the LiveRoute no matter it is matched or should be kept lived. \n\nFor example: when the user id equals to `27`, List page will be force unmounted while routing on other value  of id will be kept.\n\n```jsx\nimport NotLiveRoute from 'react-live-route'\nimport { withRouter } from 'react-router-dom'\n\nconst LiveRoute = withRouter(NotLiveRoute)\n\n\u003cLiveRoute path=\"/list\" livePath=\"/user/:id\" component={List} forceUnmount={(location, match)=\u003e match.params.id === 27}/\u003e\n```\n\n### ensureDidMount (code-splitting)\n\nensureDidMount is useful when using a route with `react-loadable`. Cause `react-loadable` will load the route component asynchronous. So the route component must give a hint to help react-live-route know when the real component is loaded so the DOM could be got.\n\n```jsx\nconst LoadableItems = Loadable({\n  loader: () =\u003e import(\"./list\"),\n  loading: () =\u003e () =\u003e \u003cp\u003exxx\u003c/p\u003e\n})\n```\n\n`List` item:\n```jsx\n  componentDidMount() {\n    this.props.ensureDidMount()\n  }\n```\n\n## TIPS\n\n### Use in `\u003cSwitch\u003e`\n\nThere's some stuff extra to do when Using with `\u003cSwitch\u003e`. If you want makes `/items` pathname alive, you must put a **placeholder** route where it should be **but renders nothing**. And put LiveRoute out of Switch.\n\n*(You have to do this because keep-alive break the origin `\u003cSwitch\u003e` or React philosophy so we have use a placeholder route to keep the philosophy and show the real content out of \u003cSwitch\u003e.)*\n\n```tsx\nfunction App() {\n  return (\n    \u003cdiv className=\"App\"\u003e\n      \u003cSwitch\u003e\n        \u003cRoute exact path=\"/\" component={Home} /\u003e\n        \u003cRoute path=\"/item/:id\" component={Detail} /\u003e\n        \u003cRoute path=\"/about\" component={About} /\u003e\n        \u003cRoute path=\"/items\" /\u003e // placeholder(required)\n        \u003cRoute path=\"*\" render={NotFound} /\u003e\n      \u003c/Switch\u003e\n      \u003cLiveRoute\n        path=\"/items\"\n        component={List}\n        livePath=\"/item/:id\"\n        name=\"items\"\n        onHide={routeState =\u003e {\n          console.log(\"[on hide]\");\n          console.log(routeState);\n        }}\n        onReappear={routeState =\u003e {\n          console.log(\"[on reappear]\");\n          console.log(routeState);\n        }}\n      /\u003e\n      \u003cBar /\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n\n\n## Licence\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffi3ework%2Freact-live-route","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffi3ework%2Freact-live-route","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffi3ework%2Freact-live-route/lists"}