Routing

The Route Table

RouteItem fields, nested routes, redirect and alias, path parameters, querying the route table, lazy routes and the route check in development mode.

Defining a route (RouteItem)

Routes are a RouteItem[] array. Each item maps a path (path) to a component (control). The example table shows the commonly used fields of RouteItem together: a pattern-constrained, named route ({id(\d+)}, name), a layout alias, an optional parameter with a default, and a redirect (an extended version of the table on the Introduction to Routing page):

import type { RouteItem } from "@motifx/core";
import MainLayout from "./layouts/MainLayout";
import NotesLayout from "./layouts/NotesLayout";
import NoteEmptyPage from "./pages/NoteEmptyPage";
import NotePage from "./pages/NotePage";
import type { Folder } from "./services/notes";

const folder = (name: Folder): RouteItem => ({
  path: `/${name}`,
  control: NotesLayout,
  meta: { folder: name },
  childs: [
    { path: "/", control: NoteEmptyPage },
    { path: "/{id(\\d+)}", name: `${name}-note`, control: NotePage },
  ],
});

export const routes: RouteItem[] = [
  {
    path: "/",
    control: MainLayout,
    childs: [
      { path: "/", redirect: "/notes" },
      { ...folder("notes"), alias: "/my-notes" },
      folder("pinned"),
      folder("archive"),
      { path: "/settings/{section?:appearance}", name: "settings", control: () => import("./pages/SettingsPage") },
      { path: "/n/{id}", redirect: "/notes/{id}" },
    ],
  },
];

import MainLayout from "./layouts/MainLayout";
import NotesLayout from "./layouts/NotesLayout";
import NoteEmptyPage from "./pages/NoteEmptyPage";
import NotePage from "./pages/NotePage";

const folder = (name) => ({
  path: `/${name}`,
  control: NotesLayout,
  meta: { folder: name },
  childs: [
    { path: "/", control: NoteEmptyPage },
    { path: "/{id(\\d+)}", name: `${name}-note`, control: NotePage },
  ],
});

export const routes = [
  {
    path: "/",
    control: MainLayout,
    childs: [
      { path: "/", redirect: "/notes" },
      { ...folder("notes"), alias: "/my-notes" },
      folder("pinned"),
      folder("archive"),
      { path: "/settings/{section?:appearance}", name: "settings", control: () => import("./pages/SettingsPage") },
      { path: "/n/{id}", redirect: "/notes/{id}" },
    ],
  },
];

What these fields do:

• A segment that does not fit the pattern does not match the route: /notes/3 matches, /notes/abc does not, and fallbacks.notFound is shown.
• The path of a route given a name is produced with href / navigateByName: app.router.href("archive-note", { id: 7 }) → /archive/7.
• An alias opens the same route at a second address, and the alias stays in the address bar: /my-notes/3.
• An optional parameter that is missing from the address gets its default: at /settings, params.section is "appearance", and at /settings/notes it is "notes".
• {id} in a redirect string is filled with the matched parameter: /n/3 → /notes/3.

RouteItem fields

The route hooks tied to navigation (onEntering, onEnter, onLeave, onUpdate) are described on the Route Hooks and Guards page.

Redirect and alias

/n/{id} in the example is a redirect in string form. If the target depends on a calculation, give a function:

const shortcuts: RouteItem[] = [
  { path: "/n/{id}", redirect: "/notes/{id}" },
  { path: "/find/{q}", redirect: (to) => "/notes?q=" + encodeURIComponent(to.params.q) },
];

const shortcuts = [
  { path: "/n/{id}", redirect: "/notes/{id}" },
  { path: "/find/{q}", redirect: (to) => "/notes?q=" + encodeURIComponent(to.params.q) },
];

redirect

• In the string form, the {param} placeholders are filled with the matched parameters. The query string (?…) and #… of the source address are carried over to the target unless the target contains its own query/#: /n/3?from=mail → /notes/3?from=mail.
• The function form receives { path, params, meta }; the path it returns is used as it is.
• The redirect is applied right after matching, before onLeave and the useGuard guards; guards and hooks run only for the target route. The source route's component is never created.
• The chain is followed (/a → /b → /c). A redirect that goes over 10 steps or comes back to a path passed earlier is stopped, the fallbacks.error page is shown at the requested address, and in development mode an MJX303 warning is written to the console.
• Only the target enters the browser history. If the address bar already shows the source path (first load, back/forward), the entry is changed with replace, so the "back" button does not get stuck on the redirect.
• Where the target came from is read through to.redirectedFrom (in the guard and onLeave context) and the redirectedFrom field of the onRouterChanged payload.
• Only the redirect of the matched leaf route is applied. If a layout has a '/' default child, the leaf that matches at the layout's path is that child; in that case a redirect written on the layout does not run, so write the redirect on the default child. The root route in the example does this: at the address /, the one that redirects is the '/' child of MainLayout.

alias

• An alias is added to the parent path by the same rule as path (alias: '/detail/{id}' under /notes → /notes/detail/{id}). Parameters are read from the alias pattern.
• The children open under a layout's alias too: in the example, /my-notes/5 → NotePage.
• The alias and the main path are the same route: moving between them with the same parameters keeps the component; if the parameters change, onUpdate runs and the page is rebuilt, as on any parameter change (keepAlive: true keeps it). The keepAlive cache is shared as well.
• If an alias clashes with the main path of another route, the main path wins. The check in development mode warns when an alias equals its own path (MJX315), when two routes use the same alias (MJX316), and when a child alias is missing the / prefix (MJX314).
• app.router.fullPath gives the matched pattern (the alias pattern for an alias), and app.router.aliasOf gives the main pattern (null if it is not an alias): at /my-notes/5, /my-notes/{id(\d+)} and /notes/{id(\d+)}. navigateByName and href always produce the main path.
• RouterLink classes look at the URL: while at /my-notes, a link with to="/notes" does not count as active.

Path parameters

Parameters are defined with the {name} syntax:

A : outside the curly braces and the rest of the segment drop out of the pattern (/user/:id → /user/, which matches no address); in development mode the check warns with MJX319.

In the ordering, a route containing {…+} or {…*} comes after routes at the same depth with the same number of static segments: /f/{a}/{b} before /f/{rest+}; /docs/{rest+}, with its static segment, before /{a}/{b}. For an unusable pattern (one that does not compile, has an unclosed ( or contains /), the check warns in development mode with MJX320.

href, navigateByName and the redirect string fill the {…} placeholders, and the values are encoded with encodeURIComponent (href('tag', { name: 'a/b' }) → /tags/a%2Fb, { name: 'café' } → /tags/caf%C3%A9).

Parameters are reached from the navigation context or the router:

import { useNavigation } from "@motifx/core";
const nav = useNavigation();
const noteId = Number(nav.params.id);

import { useNavigation } from "@motifx/core";
const nav = useNavigation();
const noteId = Number(nav.params.id);

params also contains the query string values. Like path parameters, query values are strings and arrive with their percent-encoding decoded (/notes/5?tab=history → { id: '5', tab: 'history' }, /tags/caf%C3%A9?q=a%20b → { name: 'café', q: 'a b' }); in the path + is a plain character, while in the query it is a space; values such as true, null, 2025-10-27 or {"a":1} stay text as well. If you need a number, a boolean or a date, convert the value yourself (Number(params.id)). A repeated key (?tag=work&tag=home) becomes an array of strings (['work', 'home']). A path parameter with the same name overrides the query value. The #… part never enters params.

router.uri, the uri of the onRouterChanged event, the middleware's ctx.uri and the guard's to.path are in address form: percent-encoded, the same as the address bar (/tags/caf%C3%A9). To display one, use decodeURIComponent; for the value, use params. navigate, the to of RouterLink and the onActive/onExact path can be written raw (/tags/café) or encoded; both go to the same address and make the same link active.

The query is read only from the address being navigated to: in history mode, if there is no ? in the address, params contains no query values (the previous page's query is not carried over). In hash/file mode, the query before # (/?x=1#/a) is page-level; it reaches params on every route that has no query of its own, and if the route has its own query (#/b?z=3), that one is used instead.

Querying the route table — resolve, href, routes

app.router carries three members for querying the route table without navigating:

// Which route does an address match? (does not navigate, does not touch the address bar)
const { chain, result } = app.router.resolve("/notes/5");
if (result.ok) console.log(result.route?.name, result.params.id, result.meta.folder);  // "notes-note" "5" "notes"
chain;                                      // ['/', '/notes', '/5']
result.chain.map((r) => r.path);            // ['/', '/notes', '/{id(\\d+)}']: definitions from the root to the route

// Every route in definition order (aliases excluded); for building a menu or a site map
const paths = app.router.routes.map((r) => r.fullPath);

// Which route does an address match? (does not navigate, does not touch the address bar)
const { chain, result } = app.router.resolve("/notes/5");
if (result.ok) console.log(result.route?.name, result.params.id, result.meta.folder);  // "notes-note" "5" "notes"
chain;                                      // ['/', '/notes', '/5']
result.chain.map((r) => r.path);            // ['/', '/notes', '/{id(\\d+)}']: definitions from the root to the route

// Every route in definition order (aliases excluded); for building a menu or a site map
const paths = app.router.routes.map((r) => r.fullPath);

The path of a named route is produced with href; for the to of a RouterLink, for menus and breadcrumbs. In the example the link's target is produced from a named route (nav is the router returned by useNavigation()):

<RouterLink to={nav.href(`${folder}-note`, { id: note.id })}>{note.title}</RouterLink>

const link = motifComponent(RouterLink, {
  to: nav.href(`${folder}-note`, { id: note.id }),
  childs: [motifComponent("text", (node: ComponentBase) => node.bindings.add("textContent", note, "title"))],
});

<RouterLink to={nav.href(`${folder}-note`, { id: note.id })}>{note.title}</RouterLink>

const link = motifComponent(RouterLink, {
  to: nav.href(`${folder}-note`, { id: note.id }),
  childs: [motifComponent("text", (node) => node.bindings.add("textContent", note, "title"))],
});

Lazy loading

Using () => import(...) in the control field loads the route component only when it is needed and gives automatic code splitting. A page given this way is split into a separate chunk and downloaded the first time the route is visited:

const settings: RouteItem = { path: "/settings/{section?:appearance}", name: "settings", control: () => import("./pages/SettingsPage") };

const settings = { path: "/settings/{section?:appearance}", name: "settings", control: () => import("./pages/SettingsPage") };

The loaded module must export the page as default. For a named export, map it: control: () => import("./pages/SettingsPage").then((m) => m.SettingsPage). The page cannot be built with a module that has no default export, or with some other object that is not a component: MJX304 is reported (with MJX127 as the cause) and fallbacks.error is shown.

fallbacks.notFound and fallbacks.error support the same lazy form.

A route's import() does not use a loading view or retries. To lazily load a heavy part inside a page, show a view while it loads and retry on a mobile network, use the Lazy component (see Retrying).

Route check in development mode

When app.useDevelopment(true) is called before useRouter, the route table is checked while it is being set up; a problematic definition is written to the console as a warning, and the router keeps working:

Next step

To learn where route components are placed on screen, go on to RouterView.