mobx-history-api

Browser History API with Mobx 3 and more.

Installation

npm

npm i mobx-history-api

yarn

yarn add mobx-history-api

Using

To start working with Mobx History API just get an instance of History.

import History from 'mobx-history-api'

const history = new History()

Fields

url

This is an observable field, returns current relative URL includes pathname, search and hash.

history.url // current url

url does not include locale and every time starts from /

path

This is an observable field, returns current pathname of URL.

history.path // current pathname

path does not include locale

hash

This is an observable field, returns current hash of URL.

history.hash

href

This is an observable field, returns current path + search of URL.

history.href

href does not include locale

locales

This is an observable and writable field.
Use this field when you wanna have locale prefix in the url.

history.locales = 'en|fr|ru'

Or you can provide locales via constructor.

const history = new History('ru|en|de')

locale

This is an observable and writable field, returns current locale of URL.

history.locales // returns empty string by default
history.locales = 'en|ru'

history.locale // returns empty string by default

history.push('/test')

history.url // '/test'
location.pathname // '/test'

history.locale = 'ru'

history.url // '/test'
location.pathname // '/ru/test'

history.locales = ''

history.url // '/ru/test'
location.pathname // '/ru/test'
location.locale // ''

localUrl

This is just current url with the locale

history.localUrl // '/'

history.locale = 'ru'

history.localUrl // '/ru'

movement

This is an observable field, returns undefined if you just load the page. When you moved through history the field changes to the status of the moving.

// history.movement === undefined

history.push('/test')

// history.movement === 'forward'

history.back()

// history.movement === 'back'

state

This is an observable field, returns the state of history api.
state equals window.history.state when number of steps more than 1.

history.state // {key: '...', steps: [{...}]}

history.push('/test')

history.state // {key: '...', steps: [{...}, {...}]}

Methods

search

This is an observable method.
That means you can use the method inside reaction of mobx, when result of the function changed the reaction be called.

The method returns the value of the provided key in the URL query.
search(key: string): string

history.search('key') // returns 'value' for url equals '?key=value'

push

You can push to history any URL and you be moved forward in the history.
push(url: string, position: number | string = 0, scrollFirst = false): this

history.push('/test')

By default any time when you push a new URL the page scrolls up to position 0. If you wanna custom scroll the page after the pushing you can provide the second argument as a position of scroll.

history.push('/test', 200)

history.push('/', '#root')

If you do not want to scroll, provide -1 as a position of scrolling.
If you wanna scroll first with scroll-behavior equals smooth, provide true to the third argument.

history.push('/test', 0, true)

back

You can move back like you click on back button in your browser.
back(reg?: RegExp | BackChk, def = '/', scrollFirst = false): this

history.back()

With the method, you can push to history a position which was before. Just provide an argument to the method. The argument should be regex to test previous states.

history.back(/.*/) // push any previous url

You can handle all previous steps by function

history.back(url => url !== '/test')
// push any previous url except for '/test'

The second argument is used when nothing found in history.
The third argument works the same as the third of push.

replace

You can replace url on current history position with replace.
replace(url: string, position: number | string = 0, scrollFirst = false): this

history.push('/test1')
history.push('/test2')

history.replace('/test3')

history.back()
this.url // `/test1`

history.forward()
this.url // `/test3`

go

You can move to any position of history with method go.
go(delta: number): this

history.go(-1) // the same back()

forward

You can move forward like you click on forward button in your browser.
forward(): this

history.forward()

is

This is observable method. This method just returns result of regex testing which provided to the method.
is(reg: string): boolean

history.is('^/$') // true if this is home page

The regexp tests url field of history. That means is don't include locale.

get

This method is the same as method is, but returns result of matching.
get(reg: string, index = 0, defaultValue = ''): string

history.get('^/user/([0-9]+)$')
// returns current url if it matches the regex, otherwise empty string

The second argument is used for get information inside round brackets.

history.get('^/user/([0-9]+)$', 1)
// returns current user if url matches the regex, otherwise empty string

destructor

If you finished working with history and wanna get rid of it, just run destructor method.
destructor()

history.destructor()

Utils

decode

Just decodes URL to string

import {decode} from 'mobx-history-api'

decode(location.href)

parseUrl

Returns an object with path, search and hash fields of relative URL

import {parseUrl} from 'mobx-history-api'

parseUrl(location.pathname + location.search + location.hash)

setSearch

Sets search value to relative URL

import {setSearch} from 'mobx-history-api'

setSearch('/test', 'key', 'value') // "/test?key=value"

Use 2 arguments to remove a key.

import {setSearch} from 'mobx-history-api'

setSearch('/test?key=value', 'key') // "/test"

scroll

You can scroll the current page with scroll function.
scroll(position: number | string, callback?: function): this

import {scroll} from 'mobx-history-api'

scroll(100)

If you wanna scroll the page to a defined element you can provide CSS selector to find the element and scroll to view it.

import scroll from 'mobx-history-api/scroll'

scroll('#root')

When you use scroll-behavior equals smooth you can get callback when the scrolling finished.

scroll(0, () => console.log('scrolling is finished'))

Example

import React, {Component} from 'react'
import ReactDOM from 'react-dom'
import History from 'mobx-history-api'
import {observer} from 'mobx-react'

const history = new History()

@observer
class Url extends Component {
  render () {
    return history.url
  }
}

ReactDOM.render(<Url />, document.getElementById('root'))

// render current URL. Let it be '/'

history.push('/test')

// now the root element contains '/test' 

links

• react-mobx-routing for React projects.

Issues

If you find a bug, please file an issue on GitHub