Riot Router

Simple isomorphic router

The Riot.js Router is the minimal router implementation with such technologies:

• compatible with the DOM pushState and history API
• isomorphic functional API
• erre.js streamsand javascript async generators
• rawth.jsurls parsing

It doesn't need Riot.js to work and can be used as standalone module.

For Riot.js 3 and the older route version please check thev3 branch

Table of Contents

• Install
• Documentation
• Demos

Install

We have 2 editions:

edition	file
ESM Module	index.js
UMD Version	index.umd.js
Standalone ESM Module	index.standalone.js
Standalone UMD Module	index.standalone.umd.js

Script injection

<scriptsrc= "https://unpkg /@riotjs/[email protected]/index.umd.js"></script>

Note:change the partx.x.xto the version numbers what you want to use: ex.4.5.0or4.7.0.

ESM module

import{route}from'https://unpkg /@riotjs/route/index.js'

npm

$ npm i -S @riotjs/route

Download by yourself

• Standalone
• ESM

Documentation

With Riot.js

You can import the<router>and<route>components in your application and use them as it follows:

<app>
<router>
<!-- These links will trigger automatically HTML5 history events -->
<nav>
<ahref= "/home">Home</a>
<ahref= "/about">About</a>
<ahref= "/team/gianluca">Gianluca</a>
</nav>

<!-- Your application routes will be rendered here -->
<routepath= "/home">Home page</route>
<routepath= "/about">About</route>
<routepath= "/team/:person">Hello dear { route.params.person }</route>
</router>

<script>
import{Router,Route}from'@riotjs/route'

exportdefault{
components{Router,Route}
}
</script>
</app>

You can also use theriot.registermethod to register them globally

import{Route,Router}from'@riotjs/route'
import{register}from'riot'

// now the Router and Route components are globally available
register('router',Router)
register('route',Route)

Router

The<router>component should wrap your application markup and will detect automatically all the clicks on links that should trigger a route event.

<router>
<!-- this link will trigger a riot router event -->
<ahref= "/path/somewhere">Link</a>
</router>
<!-- this link will work as normal link without triggering router events -->
<ahref= "/path/to/a/page">Link</a>

You can also specify the base of your application via component attributes:

<routerbase= "/internal/path">
<!-- this link is outside the base so it will work as a normal link -->
<ahref= "/somewhere">Link<a>
</router>

The router component has also anonStartedcallback that will be called asynchronously after the first route event will be called

<routeronStarted= "{onRouterStarted}"></router>

Route

The<route>component provides therouteproperty to its children (it's simply aURLobject) allowing you to detect the url params and queries.

<routepath= "/:some/:route/:param">{JSON.stringify(route.params)}</route>

<routepath= "/search(.*)">
<!-- Assuming the URL is "/search?q=awesome" -->

{route.searchParams.get('q')}
</route>

Each<route>component has its own lifecycle attributes in order to let you know when it gets mounted or unmounted.

<app>
<router>
<routepath="/home"
on-before-mount={onBeforeHomeMount}
on-mounted={onHomeMounted}
on-before-update={onBeforeHomeUpdate}
on-updated={onHomeUpdated}
on-before-unmount={onBeforeHomeUnmount}
on-unmounted={onHomeUnmounted}
/>
</router>
</app>

Standalone

This module was not only designed to be used with Riot.js but also as standalone module. Without importing the Riot.js components in your application you can use the core methods exported to build and customize your own router compatible with any kind of frontend setup.

Depending on your project setup you might import it as follows:

// in a Riot.js application
import{route}from'@riotjs/route'

// in a standalone context
import{route}from'@riotjs/route/standalone'

Fundamentals

This module works on node and on any modern browser, it exports therouterandrouterproperty exposed byrawth

import{route,router,setBase}from'@riotjs/route'

// required to set base first
setBase('/')

// create a route stream
constaboutStream=route('/about')

aboutStream.on.value((url)=>{
console.log(url)// URL object
})

aboutStream.on.value(()=>{
console.log('just log that the about route was triggered')
})

// triggered on each route event
router.on.value((path)=>{
// path is always a string in this function
console.log(path)
})

// trigger a route change manually
router.push('/about')

// end the stream
aboutStream.end()

Base path

Before using the router in your browser you will need to set your application base path. This setting can be configured simply viasetBasemethod:

import{setBase}from'@riotjs/route'

// in case you want to use the HTML5 history navigation
setBase(`/`)

// in case you use the hash navigation
setBase(`#`)

Setting the base path of your application route is mandatory and is the first you probably are going to do before creating your route listeners.

DOM binding

The example above is not really practical in case you are working in a browser environment. In that case you might want to bind your router to the DOM listening all the click events that might trigger a route change event. Window historypopstateevents should be also connected to the router. With theinitDomListenersmethod you can automatically achieve all the features above:

import{initDomListeners}from'@riotjs/route'

constunsubscribe=initDomListeners()
// the router is connected to the page DOM

//...tear down and disconnect the router from the DOM
unsubscribe()

TheinitDomListenerswill intercept any link click on your application. However it can also receive a HTMLElement or a list of HTMLElements as argument to scope the click listener only to a specific DOM region of your application

import{initDomListeners}from'@riotjs/route'

initDomListeners(document.querySelector('.main-navigation'))