@watch-state/react-router

This package provides you the browser routing for:

• React v16.8+
• watch-state v3+

Install

npm

npm i @watch-state/react-router

yarn

yarn add @watch-state/react-router

The simplest way of using is Create React App.

Router

Use Router anywhere to show content by URL matching.

import Router, {history} from '@watch-state/react-router'
// or
// import Router, {history} from '@watch-state/react-router/Router'

const App = () => (
  <div>
    <button onClick={() => history.push('/')}>home</button> |
    <button onClick={() => history.push('/test')}>test</button>
    <div>
      This is
      <Router path='/'>
         home
      </Router>
      <Router path='/test'>
        test
      </Router>
      page
    </div>
  </div>
)

The history is @watch-state/history-api.

path

Use path to show router content by URL path

const Test = () => <Router path='/test'>test</Router>

test will be shown when url equals /test or /test?key=value#test but not for /test/420 or /user/test.

You can use it as regexp.

const Test = () => <Router path='/(foo|bar)'>test</Router>

test will be shown when url path equals /foo or /bar.

You can get foo or bar by children function

const Test = () => <Router path='/(foo|bar)'>{get => get(1)}</Router>

/foo returns foo and /bar returns bar.

The number in the get function says which brackets you want to use.

const Test = () => <Router path='/(foo|bar)/(\d+)'>{get => get(2)}</Router>

/foo/13 returns 13 and /bar/420 returns 420.

match

Use match if you want to match URL by custom regexp

const Test = () => <Router match='^/(foo|bar)'>FOOBAR</Router>

/foo/13 returns FOOBAR and /bar returns FOOBAR.

If you use match then path, search, hash, ish, pathIsh, searchIsh and hashIsh are not be used.
You can use a function as a child to get the value of the matching like for path.

pathIsh

Use pathIsh to make the soft routing by path. That means the path should start with path property.

const Test = () => <Router path='/(foo|bar)' pathIsh>FOOBAR</Router>

/foo/13 returns FOOBAR and /bar/420/test?key=value#test returns FOOBAR.
Starts with /foo or /bar.

ish

Use ish instead of pathIsh, searchIsh and hashIsh equal true

const Test = () => <Router path='/(foo|bar)' ish>FOOBAR</Router>

The same as pathIsh

search

Use search if you want to show content by search query of URL.

const Test = () => <Router search='key=value'>test</Router>

/foo/13?key=value#420 returns test but /foo/13?key=value&test returns empty content.

searchIsh

Use searchIsh or ish to make a soft search.

const Test = () => <Router search='key=value' ish>test</Router>

now /foo/13?key=value&test and /foo/13?test=1&key=value&foo=bar returns test.

Also, you can use only key for search

const Test = () => <Router search='key' ish>test</Router>

/?key&value and /?value&key returns test but /?key=1 and /?key1 returns nothing.

hash

Use hash if you want to show content by hash of URL.

const Test = () => <Router hash='test'>test</Router>

/any/path?any=search#test returns test but /#test1 returns empty content.

hashIsh

Use hashIsh or ish to fix it.

const Test = () => <Router hash='test' ish>test</Router>

now /#test1 and /#sometextwiththetestword returns test.

other

This is an alternative of react Switch.

Router with other shows content only if all routers without other in the same Router are not matched.

const Test = () => (
 <Router>
   <Router path='/'>home</Router>
   <Router path='/user'>user</Router>
   <Router other>other</Router>
 </Router>
)

will show home for /, user for /user and other for any other url

You may use any structure inside Router and several other routers with any props.

const Test = () => (
 <Router>
   <div>
     <Router path='/'>home</Router>
     <div>
       content
       <Router path='/user'>user</Router>
     </div>
     <Router search='modal' other>modal</Router>
     <Router other>
       <Router path='/test'>test</Router>
       <Router other><div>other</div></Router>
     </Router>
   </div>
 </Router>
)

showDelay

You can show content of router with delay.

const Test = () => <Router path='/test' showDelay={1000}>test</Router>

when URL became /test the content be not shown, test will be shown in a second after that.

hideDelay

This is the same showDelay but for hiding.

const Test = () => <Router path='/test' hideDelay={1000}>test</Router>

when URL became /test the content be shown immediately, but when URL is changed after that, test will be hidden in a second.

delay

This is the combine of showDelay and hideDelay.

const Test = () => <Router path='/test' delay={1000}>test</Router>

test will be shown or hidden in a second.

onShow

It calls any time when the content will be shown

const Test = () => (
  <Router
    path='/test'
    onShow={() => console.log('test')}>
    test
  </Router>
)

onShown

It calls any time when the content has shown

const Test = () => (
  <Router
    path='/test'
    delay={1000}
    onShown={() => console.log('test')}>
    test
  </Router>
)

onHide

It calls any time when the content will be hidden

const Test = () => (
  <Router
    path='/test'
    onHide={() => console.log('test')}>
    test
  </Router>
)

onHidden

It calls any time when the content has hidden

const Test = () => (
  <Router
    path='/test'
    delay={1000}
    onHidden={() => console.log('test')}>
    test
  </Router>
)

Redirect

Use the component for comfortable redirection

import {Redirect} from '@watch-state/react-router'

url

Use the prop to redirect at the url.

const RedirectToHome = () => (
  <Redirect url='/' />
)

const RedirectToLogin = () => (
  <Redirect url='?modal=login' />
)

const RedirectToHeader = () => (
  <Redirect url='#root' />
)

const RedirectToRepo = () => (
  <Redirect url='https://github.com/d8corp/watch-state-react-router' />
)

path

The same as url but works only with path.

const RedirectToHome = () => (
  <Redirect path='/' />
)

You may combine with url

const RedirectToHome = () => (
  <Redirect url='/foo#bar' path='/' />
)
// redirects to /#bar

search

The same as path but works with search and you may combine with url

const RedirectToLoginModal = () => (
  <Redirect search='modal=login' />
)
// redirects to ?modal=login

You may use an object of search keys and values

const RedirectToLoginModal = () => (
  <Redirect search={{modal: 'login'}} />
)
// redirects to ?modal=login

undefined value removes the key

history.push('/test?key=value')

render (
  <Redirect search={{key: undefined}} />
)
// redirects to /test

hash

The same as path but works with hash and you may combine with url

const RedirectToRoot = () => (
  <Redirect hash='root' />
)
// redirects to #root

push

By default Redirect replaces url. If you wanna push the redirection to history use the property.

const RedirectToHome = () => (
  <Redirect path='/' push />
)

position

By default the page scrolls up during redirection. You may change the scroll position by the property.

const RedirectToHome = () => (
  <Redirect path='/' position={60} />
)

You may scroll to any element by selector query

const RedirectToHome = () => (
  <Redirect path='/' position='#root' />
)

scrollFirst

When you use smooth scroll you can wait while the scrolling finished and then make the redirection.

const RedirectToHome = () => (
  <Redirect path='/' scrollFirst />
)

Link

Use the component instance of a.

rel="noreferrer" and target="_blank" are default for external links.

href

If href starts from / then the Link will use History API.

/ is default value of href.

const App = () => (
  <>
    <div>
      <Link>Home</Link>
      <Link href='/test'>Test</Link>
    </div>
    <Router path='/'>Home</Router>
    <Router path='/test'>Test</Router>
  </>
)

When href starts from ? the Link will keep the pathname and change the search and hash.

const App = () => (
  <>
    <div>
      <Link>Home</Link>
      <Link href='/test'>Test</Link>
      <Link href='?modal=test'>Test Modal</Link>
    </div>
    <Router path='/'>Home</Router>
    <Router path='/test'>Test</Router>
    <Router search='modal=test'><div>Test Modal</div></Router>
  </>
)

When href starts from # the Link will keep the whole URL except for hash.

replace

By default Link pushes to history but you may use replace to replace current history state.

const Agree = () => (
  <Link replace href='?'>I agree</Link>
)

href='?' means clearing of search and hash

activeClass

If you set activeClass then the link will have the class if url starts from href

const Test = () => (
  <Link activeClass='active' href='/test'>test</Link>
)

When you click the link html will be equal

<a class="active" href="/test">test</a>

exact

By default activeClass will be applied when url starts from href but use exact to compare exactly.

const Test = () => (
  <Link activeClass='active' href='/test' exact>test</Link>
)

scrollTo

If you wanna scroll the page to custom position (by default it's up of the page) use scrollTo

const To100 = () => (
  <Link scrollTo={100} href='/test'>test</Link>
)

const ToRoot = () => (
  <Link scrollTo='#root' href='/test'>test</Link>
)

Negative value keep the page on the same scroll position.

const NoScroll = () => (
  <Link scrollTo={-1} href='/test'>test</Link>
)

scrollFirst

When you use smooth scroll you can wait while the scrolling finished and then make the redirection.

const Test = () => (
  <Link scrollFirst href='/test'>test</Link>
)

onMove

If you wanna wait for something before the move by the link then the property for you.

const Test = () => (
  <Link href='/test' onMove={move => setTimeout(move, 100)}>test</Link>
)

links

• @watch-state/history-api - routing with History API
• package content

issues

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