@mazzard/mobx-history v2.0.4

@mazzard/mobx-history

History api with mobx.
github | npm

Installation

npm

npm i @mazzard/mobx-history

yarn

yarn add @mazzard/mobx-history

Using

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

import History from '@mazzard/mobx-history'

const history = new History()

Fields

url

This is observable field, returns current URL.
string

const currentUrl = history.url

path

This is observable field, returns current path of URL.
string

const currentPath = history.path

hash

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

const currentHash = history.hash

href

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

const currentHref = history.href

movement

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

// history.movement === undefined
history.push('/test')
// history.movement === 'forward'
history.back()
// history.movement === 'back'

Methods

search

This is an observable method. 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'

scroll

You can scroll current page with scroll method of history.
scroll(position: number | string, attempts = 3, delay = 500): this

history.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.

history.scroll('#root')

push

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

history.push('/test')

By default any time 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.

back

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

history.back()

With the back 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

The second argument is used when nothing found in history.

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. That means you can use the method inside reaction of mobx, when result of the function changed the reaction be called. This method just returns result of regex testing which provided to the method.
is(reg: string, prefix = ''): boolean

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

Use prefix to reduce URL

history.is('^/user$', '/en') // true for `/user` and `/en/user`

get

This method is the same method is, but returns result of matching.
get(reg: string, index = 0, defaultValue = '', prefix = ''): 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

Use prefix the same for is method

destructor

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

history.destructor()

Example

import React from 'react'
import ReactDOM from 'react-dom'
import History from '@mazzard/mobx-history'
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'