README
@watch-state/history-api
Browser History API with watch-state.
Installation
npm
npm i @watch-state/history-api
yarn
yarn add @watch-state/history-api
Using
To start working with watch-state History API just get an instance of History
.
import History from '@watch-state/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 a watcher of watch-state
,
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('^/