Skip to main content

Router

The kea-router plugin provides a nice wrapper around window.History and helps manage the URL in your application. Use it to listen to route changes or change the URL yourself. There are a few helpers (actionToUrl and urlToAction) that help track the URL changes, or access the router directly to manually control the browser history object.

Installation#

First install the kea-router package:

# if you're using yarn
yarn add kea-router
# if you're using npm
npm install --save kea-router

Then install the plugin:

import { routerPlugin } from 'kea-router'
import { resetContext } from 'kea'
resetContext({
plugins: [
routerPlugin({
/* options */
}),
],
})

Configuration options#

The plugin takes the following options:

routerPlugin({
// The browser History API or something that mocks it
// Defaults to window.history in the browser and a mock memoryHistory otherwise
history: window.history,
// An object with the keys { pathname, search, hash } used to
// get the current location. Defaults to window.location in the browser and
// an empty object otherwise.
location: window.location,
// If there is a difference between the path in the browser and the path in
// your routes, use these functions to clear it up.
// For example to have the same app on many subfolders in one the site.
pathFromRoutesToWindow: (path) => '/subfolder' + path,
pathFromWindowToRoutes: (path) => path.replace(/^\/subfolder/, ''),
// kea-router has support for (de)serializing the search and hash parameters
// It comes with sensible default functions, yet you can override them here
encodeParams: (obj = { key: 'value' }, symbol = '?') => '?key=value',
decodeParams: (input = '?key=value', symbol = '?') => ({ key: 'value' }),
})

Sample usage#

Use actionToUrl to change the URL in response to actions and urlToAction to dispatch actions when the route changes

import { kea } from 'kea'
export const articlesLogic = kea({
actionToUrl: ({ values }) => ({
openList: ({ id }) => `/articles`,
openArticle: ({ id }) => `/articles/${id}`,
openComments: () => `/articles/${values.article.id}/comments`,
closeComments: () => `/articles/${values.article.id}`
}),
urlToAction: ({ actions }) => ({
'/articles': () => actions.openList(),
'/articles/:id(/:extra)': ({ id, extra }) => {
actions.openArticle(id)
if (extra === 'comments') {
actions.openComments()
} else {
actions.closeComments()
}
},
}),
// Skipped in the examples: the actions, reducers, etc for the above
actions: { ... },
reducers: { ... },
selectors: { ... }
})

Url Pattern#

kea-router uses the url-pattern library under the hood to match paths. Please see its documentation for all supported options.

UrlToAction#

Search and Hash parameters#

kea-router has built in support for serializing and deserializing search and hash URL parameters, such as:

// "pathname" + "?search" + "#hash"
url = 'http://example.com/path?searchParam=true#hashParam=nah'

The second and third parameters to urlToAction are searchParams and hashParams respectively. These are deserialized objects that you can use directly.

Full example#

import { kea } from 'kea'
export const articlesLogic = kea({
urlToAction: ({ actions }) => ({
// Synax:
// urlToAction: ({ actions }) => ({
// '/path': (pathParams, searchParams, hashParams, payload) => {
// // ...
// }
// })
//
// Example on url: "/articles?id=123&comments=true#hashKey=hurray"
// --> pathParams = {}
// --> searchParams = { id: 123, comments: true }
// --> hashParams = { hashKey: 'hurray' }
// --> payload = // payload for router.actions.locationChanged
'/articles': (_, { id, comments }, { hashKey }) => {
if (id) {
actions.openArticle(id)
if (comments) {
actions.openComments()
} else {
actions.closeComments()
}
} else {
actions.openList()
}
},
}),
})

For actionToUrl, you may include the search and hash parts directly in the URL or return an array in the format: [pathname, searchParams, hashParams]. The searchParams and hashParams can be both strings or objects.

import { kea } from 'kea'
export const articlesLogic = kea({
actionToUrl: ({ values }) => ({
// Use one of:
// - action: () => url,
// - action: () => [url, searchParams, hashParams],
openList: ({ id }) => `/articles`,
// these three are equivalent
openArticle: ({ id }) => `/articles?id=${id}`,
openArticle: ({ id }) => [`/articles`, { id }],
openArticle: ({ id }) => [`/articles`, `?id=${id}`],
openComments: () => [`/articles`, { id: values.article.id, comments: true }],
closeComments: () => [`/articles`, { id: values.article.id }, '#hashKey=true'],
}),
})

Control the route directly#

Import router to control the router directly in your components

import React from 'react'
import { useActions, useValues } from 'kea'
import { router } from 'kea-router'
export function MyComponent() {
const { push, replace } = useActions(router)
const {
location: { pathname, search, hash }, // strings
searchParams, // object
hashParams, // object
} = useValues(router)
return (
<div>
{pathname === '/setup' ? <Setup /> : <Dashboard />}
<button onclick={() => push('/setup')}>Open Setup</button>
</div>
)
}

Or in a logic:

import { kea } from 'kea'
import { router } from 'kea-router'
const logic = kea({
actions: {
buttonPress: true,
},
listeners: {
buttonPress: () => {
if (router.values.location.pathname !== '/setup') {
router.actions.push('/setup', { search: 'param' }, '#integration')
}
},
},
})

Both the push and replace actions accept searchParams and hashParams as their second and third arguments. You can provide both an object or a string for them. You can also include the search and hash parts in the url.

Link tag#

Use the included <A> tag to link via the router. This changes the URL via router.actions.push() instead of reloading the entire page.

import React from 'react'
import { A } from 'kea-router'
// use <A href=''> instead of <a href=''> to open links via the router
export function Page() {
return (
<ul>
<li>
<A href="/about">About me</A>
</li>
<li>
<A href="/contact">Contact</A>
</li>
</ul>
)
}

Listen to location changes#

In case urlToAction is not sufficient for your needs, listen to the locationChanged action to react to URL changes manually:

import { kea } from 'kea'
import { router } from 'kea-router'
const otherLogic = kea({
listeners: {
[router.actions.locationChanged]: ({ pathname, search, hash, method }) => {
console.log({ pathname, search })
},
},
})

Global scene router#

Here's sample code for a global scene router

import React, { lazy } from 'react'
export const scenes = {
error404: () => <div>404</div>,
dashboard: lazy(() => import('./dashboard/DashboardScene')),
login: lazy(() => import('./login/LoginScene')),
projects: lazy(() => import('./projects/ProjectsScene')),
}
export const routes = {
'/': 'dashboard',
'/login': 'login',
'/projects': 'projects',
'/projects/:id': 'projects',
}
export const sceneLogic = kea({
actions: {
setScene: (scene, params) => ({ scene, params }),
},
reducers: {
scene: [
null,
{
setScene: (_, payload) => payload.scene,
},
],
params: [
{},
{
setScene: (_, payload) => payload.params || {},
},
],
},
urlToAction: ({ actions }) => {
return Object.fromEntries(
Object.entries(routes).map(([path, scene]) => {
return [path, (params) => actions.setScene(scene, params)]
})
)
},
})
export function Layout({ children }) {
return (
<div className="layout">
<div className="menu">...</div>
<div className="content">{children}</div>
</div>
)
}
export function Scenes() {
const { scene, params } = useValues(sceneLogic)
const Scene = scenes[scene] || scenes.error404
return (
<Layout>
<Suspense fallback={() => <div>Loading...</div>}>
<Scene {...params} />
</Suspense>
</Layout>
)
}

Utility functions#

kea-router exposes three functions to help manage urls in your app:

import { encodeParams, decodeParams, combineUrl } from 'kea-router'
// Use `encodeParams` to convert an object to part of a path
// --> encodeParams(object, symbol)
encodeParams({ key: 'value' }, '?') === '?key=value'
// Use `decodeParams` to convert a part of a path to an object
// --> decodeParams(object, symbol)
decodeParams('?key=value', '?') === { key: 'value' }
decodeParams('key=value', '?') === { key: 'value' }
// Use `combineUrl` to both split an existing url into its components and
// to merge new search and hash parts into an existing url.
// --> combineUrl(url, searchInput, hashInput, encodeParams, decodeParams)
// - `searchInput` and `hashInput` can be either a string or an object
// - `encodeParams` and `decodeParams` can be overridden if needed
combineUrl('/path?key=value#hash') ===
{
url: '/path?key=value#hash',
pathname: '/path',
search: '?key=value',
searchParams: { key: 'value' },
hash: '#hash',
hashParams: { hash: null },
}
combineUrl('/path?key=value#hash', { key: 'otherValue' }, '#addHash=bla') ===
{
url: '/path?key=otherValue#hash&addHash=bla',
pathname: '/path',
search: '?key=otherValue',
searchParams: { key: 'otherValue' },
hash: '#hash&addHash=bla',
hashParams: { hash: null, addHash: 'bla' },
}