{"id":23366736,"url":"https://github.com/d8corp/mobx-history-api","last_synced_at":"2025-04-07T23:15:54.596Z","repository":{"id":39410772,"uuid":"262032680","full_name":"d8corp/mobx-history-api","owner":"d8corp","description":"Browser History Api with mobx","archived":false,"fork":false,"pushed_at":"2023-01-06T06:29:57.000Z","size":235,"stargazers_count":2,"open_issues_count":12,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-21T09:03:58.040Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/d8corp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2020-05-07T11:33:25.000Z","updated_at":"2020-10-08T13:58:48.000Z","dependencies_parsed_at":"2023-02-05T13:00:22.929Z","dependency_job_id":null,"html_url":"https://github.com/d8corp/mobx-history-api","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d8corp%2Fmobx-history-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d8corp%2Fmobx-history-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d8corp%2Fmobx-history-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d8corp%2Fmobx-history-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d8corp","download_url":"https://codeload.github.com/d8corp/mobx-history-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247744328,"owners_count":20988783,"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":[],"created_at":"2024-12-21T14:17:29.988Z","updated_at":"2025-04-07T23:15:54.569Z","avatar_url":"https://github.com/d8corp.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mobx-history-api\n[![NPM](https://img.shields.io/npm/v/mobx-history-api.svg)](https://github.com/d8corp/mobx-history-api/blob/master/CHANGELOG.md)\n[![downloads](https://img.shields.io/npm/dm/mobx-history-api.svg)](https://www.npmjs.com/package/mobx-history-api)\n[![license](https://img.shields.io/npm/l/mobx-history-api)](https://github.com/d8corp/mobx-history-api/blob/master/LICENSE)  \nBrowser History API with [Mobx](https://mobx.js.org/README.html) 3 and more.\n### Installation\nnpm\n```bash\nnpm i mobx-history-api\n```\nyarn\n```bash\nyarn add mobx-history-api\n```\n### Using\nTo start working with Mobx History API just get an instance of `History`.\n```javascript\nimport History from 'mobx-history-api'\n\nconst history = new History()\n```\n## Fields\n### url ![string](https://img.shields.io/badge/-string-green)\nThis is an observable field, returns current relative URL includes pathname, search and hash.  \n```javascript\nhistory.url // current url\n```\n*`url` does not include locale and every time starts from `/`*\n### path ![string](https://img.shields.io/badge/-string-green)\nThis is an observable field, returns current pathname of URL.  \n```javascript\nhistory.path // current pathname\n``` \n*`path` does not include locale*\n### hash ![string](https://img.shields.io/badge/-string-green)\nThis is an observable field, returns current hash of URL.  \n```javascript\nhistory.hash\n```  \n### href ![string](https://img.shields.io/badge/-string-green)\nThis is an observable field, returns current path + search of URL.\n```javascript\nhistory.href\n```\n*`href` does not include locale*\n### locales ![string](https://img.shields.io/badge/-string-green)\nThis is an observable and writable field.  \nUse this field when you wanna have locale prefix in the url.\n```javascript\nhistory.locales = 'en|fr|ru'\n```\nOr you can provide `locales` via constructor.\n```javascript\nconst history = new History('ru|en|de')\n```\n### locale ![string](https://img.shields.io/badge/-string-green)\nThis is an observable and writable field, returns current locale of URL.\n```javascript\nhistory.locales // returns empty string by default\nhistory.locales = 'en|ru'\n\nhistory.locale // returns empty string by default\n\nhistory.push('/test')\n\nhistory.url // '/test'\nlocation.pathname // '/test'\n\nhistory.locale = 'ru'\n\nhistory.url // '/test'\nlocation.pathname // '/ru/test'\n\nhistory.locales = ''\n\nhistory.url // '/ru/test'\nlocation.pathname // '/ru/test'\nlocation.locale // ''\n```\n### localUrl ![string](https://img.shields.io/badge/-string-green)\nThis is just current url with the locale\n```javascript\nhistory.localUrl // '/'\n\nhistory.locale = 'ru'\n\nhistory.localUrl // '/ru'\n```\n### movement ![string](https://img.shields.io/badge/-\"forvard\"-green) ![string](https://img.shields.io/badge/-\"back\"-green) ![undefined](https://img.shields.io/badge/-undefined-orange)\nThis is an observable field, returns `undefined` if you just load the page.\nWhen you moved through history the field changes to the status of the moving.  \n```javascript\n// history.movement === undefined\n\nhistory.push('/test')\n\n// history.movement === 'forward'\n\nhistory.back()\n\n// history.movement === 'back'\n```\n### state ![object](https://img.shields.io/badge/-object-orange)\nThis is an observable field, returns the state of history api.  \n`state` equals `window.history.state` when number of `steps` more than 1.\n```javascript\nhistory.state // {key: '...', steps: [{...}]}\n\nhistory.push('/test')\n\nhistory.state // {key: '...', steps: [{...}, {...}]}\n```\n## Methods\n### search\nThis is an observable method.  \nThat means you can use the method inside `reaction` of `mobx`,\nwhen result of the function changed the `reaction` be called.  \n\nThe method returns the value of the provided `key` in the URL query.   \n`search(key: string): string`\n```javascript\nhistory.search('key') // returns 'value' for url equals '?key=value'\n```\n### push\nYou can push to history any URL and you be moved forward in the history.  \n`push(url: string, position: number | string = 0, scrollFirst = false): this`\n```javascript\nhistory.push('/test')\n``` \nBy default any time when you push a new URL the page scrolls up to position `0`.\nIf you wanna custom scroll the page after the pushing you can provide the second argument as a position of scroll.\n```javascript\nhistory.push('/test', 200)\n\nhistory.push('/', '#root')\n```\nIf you do not want to scroll, provide `-1` as a position of scrolling.  \nIf you wanna scroll first with `scroll-behavior` equals `smooth`, provide `true` to the third argument.\n```javascript\nhistory.push('/test', 0, true)\n```\n### back\nYou can move back like you click on back button in your browser.  \n`back(reg?: RegExp | BackChk, def = '/', scrollFirst = false): this`\n```javascript\nhistory.back()\n```\nWith the method, you can push to history a position which was before.\nJust provide an argument to the method.\nThe argument should be regex to test previous states.\n```javascript\nhistory.back(/.*/) // push any previous url\n```\nYou can handle all previous steps by function\n```javascript\nhistory.back(url =\u003e url !== '/test')\n// push any previous url except for '/test'\n```\nThe second argument is used when nothing found in history.  \nThe third argument works the same as the third of `push`.\n### replace\nYou can replace url on current history position with `replace`.  \n`replace(url: string, position: number | string = 0, scrollFirst = false): this`\n```javascript\nhistory.push('/test1')\nhistory.push('/test2')\n\nhistory.replace('/test3')\n\nhistory.back()\nthis.url // `/test1`\n\nhistory.forward()\nthis.url // `/test3`\n```\n### go\nYou can move to any position of history with method `go`.  \n`go(delta: number): this`\n```javascript\nhistory.go(-1) // the same back()\n```\n### forward\nYou can move forward like you click on forward button in your browser.  \n`forward(): this`\n```javascript\nhistory.forward()\n```\n### is\nThis is observable method.\nThis method just returns result of regex testing which provided to the method.  \n`is(reg: string): boolean`\n```javascript\nhistory.is('^/$') // true if this is home page\n```\nThe regexp tests `url` field of `history`. That means `is` don't include `locale`.\n### get\nThis method is the same as method `is`, but returns result of matching.  \n`get(reg: string, index = 0, defaultValue = ''): string`\n```javascript\nhistory.get('^/user/([0-9]+)$')\n// returns current url if it matches the regex, otherwise empty string\n```\nThe second argument is used for get information inside round brackets.\n```javascript\nhistory.get('^/user/([0-9]+)$', 1)\n// returns current user if url matches the regex, otherwise empty string\n```\n### destructor\nIf you finished working with history and wanna get rid of it, just run `destructor` method.  \n`destructor()`\n```javascript\nhistory.destructor()\n```\n## Utils\n### decode\nJust decodes URL to string\n```javascript\nimport {decode} from 'mobx-history-api'\n\ndecode(location.href)\n```\n### parseUrl\nReturns an object with `path`, `search` and `hash` fields of relative URL\n```javascript\nimport {parseUrl} from 'mobx-history-api'\n\nparseUrl(location.pathname + location.search + location.hash)\n```\n### setSearch\nSets search value to relative URL\n```javascript\nimport {setSearch} from 'mobx-history-api'\n\nsetSearch('/test', 'key', 'value') // \"/test?key=value\"\n```\nUse 2 arguments to remove a key.\n```javascript\nimport {setSearch} from 'mobx-history-api'\n\nsetSearch('/test?key=value', 'key') // \"/test\"\n```\n### scroll\nYou can scroll the current page with `scroll` function.  \n`scroll(position: number | string, callback?: function): this`\n```javascript\nimport {scroll} from 'mobx-history-api'\n\nscroll(100)\n```\nIf you wanna scroll the page to a defined element you can provide CSS selector to find the element and scroll to view it.\n```javascript\nimport scroll from 'mobx-history-api/scroll'\n\nscroll('#root')\n```\nWhen you use `scroll-behavior` equals `smooth` you can get callback when the scrolling finished.\n```javascript\nscroll(0, () =\u003e console.log('scrolling is finished'))\n```\n## Example\n```javascript\nimport React, {Component} from 'react'\nimport ReactDOM from 'react-dom'\nimport History from 'mobx-history-api'\nimport {observer} from 'mobx-react'\n\nconst history = new History()\n\n@observer\nclass Url extends Component {\n  render () {\n    return history.url\n  }\n}\n\nReactDOM.render(\u003cUrl /\u003e, document.getElementById('root'))\n\n// render current URL. Let it be '/'\n\nhistory.push('/test')\n\n// now the root element contains '/test' \n```\n### links\n- [react-mobx-routing](https://github.com/d8corp/react-mobx-routing) [![NPM](https://img.shields.io/npm/v/react-mobx-routing.svg)](https://www.npmjs.com/package/react-mobx-routing) for React projects. \n## Issues\nIf you find a bug, please file an issue on [GitHub](https://github.com/d8corp/mobx-history-api/issues)  \n[![issues](https://img.shields.io/github/issues-raw/d8corp/mobx-history-api)](https://github.com/d8corp/mobx-history-api/issues)  \n\u003e ---\n[![stars](https://img.shields.io/github/stars/d8corp/mobx-history-api?style=social)](https://github.com/d8corp/mobx-history-api/stargazers)\n[![watchers](https://img.shields.io/github/watchers/d8corp/mobx-history-api?style=social)](https://github.com/d8corp/mobx-history-api/watchers)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd8corp%2Fmobx-history-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd8corp%2Fmobx-history-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd8corp%2Fmobx-history-api/lists"}