Xstate Router

XState Router. Add routes to your XState machine.
Alternatives To Xstate Router
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Mux17,92910,8199,2543 months ago23December 12, 202133bsd-3-clauseGo
A powerful HTTP router and URL matcher for building Go web servers with 🦍
Page.js7,4691,354217a year ago48April 21, 2020127JavaScript
Micro client-side router inspired by the Express router
Director5,5173,4341993 years ago29February 04, 2015128mitJavaScript
a tiny and isomorphic URL router for JavaScript
Router4,614354 days ago127January 31, 202220mitTypeScript
🤖 Type-safe router w/ built-in caching & URL state management for JS/TS, React, Preact, Solid, Vue, Svelte and Angular
5 years ago36JavaScript
:hamburger: like meteor, but meatier :hamburger:
Skipper2,8432318 hours ago1,004September 23, 2022221otherGo
An HTTP router and reverse proxy for service composition, including use cases like Kubernetes Ingress
Klein.php2,630362657 months ago9February 01, 201797mitPHP
A fast & flexible router
Next Routes2,439686782 months ago46May 21, 2018mitJavaScript
Universal dynamic routes for Next.js
Navigo2,334215432 years ago161April 23, 20219mitTypeScript
A simple vanilla JavaScript router.
Router51,70712679a year ago148March 19, 202094mitTypeScript
Flexible and powerful universal routing solution
Alternatives To Xstate Router
Select To Compare

Alternative Project Comparisons


XState Router. Add routes to your XState machine and maintain it in sync with the actual route.


Install the library with npm i xstate-router.

If you don't have XState installed, install it: npm i xstate

Try the live example here: https://codesandbox.io/s/rllly3pyxp.

The routerMachine function returns an interpreter:

import { routerMachine } from 'xstate-router'

const machineConfig = {
    initial: 'main',
    context: { myValue: 0 },
    states: {
        main: { meta: { path: '/' } },
        blog: { meta: { path: '/blog' } },

const service = routerMachine({
    config: machineConfig,

// The state changes on a route change and the route changes on a state change.
service.onTransition(state => console.log(state.value))

// The context is enhanced with router properties.
service.onChange(ctx => console.log(ctx))
/* Context
        myValue: 0,
        // Router properties:

Use with React Hooks

import { useRouterMachine } from 'xstate-router'

const config = {
  initial: 'home',
  states: {
    home: { meta: { path: '/' }, on: { NEXT: 'about' } },
    about: { meta: { path: '/about' }, on: { NEXT: 'dashboard' } },
    dashboard: {
      meta: { path: '/dashboard' },
      initial: 'login',
      on: { NEXT: 'home' },
      states: {
        loggedIn: {
          initial: 'main',
          states: {
            main: { meta: { path: '/dashboard/main' } },
            data: { meta: { path: '/dashboard/data' } }
        login: {
          meta: { path: '/dashboard/login' },
          on: { LoggedIn: 'loggedIn' }

function App() {
    const service = useRouterMachine({ config })

    return <div>{service.state.value}</div>

Enhanced context

  1. match: Tells you whether the route in the location matches the current state's path. If it matches it contains an object holding properties for each route parameter's value if the path was parameterized. Examples: null (not matching), {} (no parameters), { param1: 4711 }
  2. location: The current value of history.location
  3. history: routerMachine(...) accepts a history object as fourth parameter. If it is missing it defaults to createBrowserHistory() (from package 'history') and is published in the context.

if you translate to a state having a parameterized route then you have to ensure that context.match contains the values of those parameters. Otherwise the placeholder is shown in the route. Example:

  states: {
      list: { meta: { path: '/items' },
         on: {
            ShowDetails: {
                target: 'details',
                actions: assign((ctx, event) => ({
                                    match: { id: event.item }
      details: { meta: { path: '/items/:id/details'} }

where the event trigger could look like this:

<button onClick={() => this.send('ShowDetails', { item: 817 })}>Show details...</button>


Paths could have parameters such as /items/:id/details and regular expressions, for more information please read this: pillarjs/path-to-regexp.

Router events

If a route changes then a parameterized event 'route-changed' is fired: e.g. { dueToStateTransition: "true", route: "/blog", service: /* the xstate interpreter */ }.

  1. If the route changes because a state is entered which has a route configured, then dueToStateTransition is true. If the route changes because the location was changed (either by the user in the browsers location bar or by a script changing history.location), then dueToStateTransition is false.
  2. route gives you the current route which causes the event
  3. service provides the xstate interpreter which can be used to send another event.

Placing an on: 'router-changed' event at a state can be used to avoid leaving the current state if the route changes. Think of a state which might show unsaved data and you want to ask the user 'Leave and loose unsaved data?'. If you decide to accept the new route anyway you have to resend the event:

  on: {
    'route-changed': {
      cond: (context, event) => event.dueToStateTransition === false
          && !event.processed,            // interfere only new events
      actions: (context, event) => {
        if (context.unsavedData) return;  // suppress current route change
        event.processed = true;           // mark event as processed
        event.service.send(event);        // resend the event to establish the origin route change
Popular Routes Projects
Popular Router Projects
Popular Networking Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
State Machine
State Management