@k8ordo/router

Route table

Write the route table with defineRoutes and decide which page each path becomes.

On this page

Pages and layouts

src/routes.ts
export const routes = defineRoutes({
  '/': Home,
  '/products': {
    layout: ProductsLayout,
    children: {
      '/': ProductList,
      '/:id': ProductPage,
    },
  },
});

A value in the route table is either a page component or an object with children. The object groups the pages below it and wraps them in its layout when it has one.

A key in children continues the parent’s pattern: /:id is the page at /products/:id, and / is the page at /products. At /products/42, ProductPage renders where ProductsLayout places its <Outlet />.

Objects nest, and their layouts nest with them from the outside in. A trailing slash is ignored when matching, so /products/ is the same page as /products.

Information

Note

The object can also hold error and loading. See Errors and loading for how to write them.

Path params

ts
const routes = defineRoutes({ '/products/:id': ProductPage });

routes.match('/products/42')?.params; // { id: '42' }
routes.match('/products/a%2Fb')?.params; // { id: 'a/b' }
routes.match('/products/a/b'); // null
routes.match('/products/'); // null

A :name segment takes the string at that position in the path: exactly one non-empty segment, never across a /. The value is decoded, so %2F comes back as /.

The type of the params comes from the pattern string. /:locale/products/:id gives { locale: string; id: string }.

match is the same matching <Router> performs, as a plain function. It needs no browser, so it is a quick way to check which page a path becomes.

/*

ts
const routes = defineRoutes({
  '/': Home,
  '/products/:id': ProductPage,
  '/*': NotFound,
});

routes.match('/products/42/reviews')?.pattern; // '/*'
routes.match('/no/such/page')?.pattern; // '/*'

/* takes every path no pattern above it matched. Unlike :name, it takes any number of segments. What it takes does not become a param.

Written after a prefix, as in /products/*, it matches only the paths below /products, not /products itself.

/* is a pattern to match, not one to link to. Passed to href, it throws a TypeError at runtime ("/*" is a wildcard — it has no href).

Warning

Pitfall

With /* at the end of the table, give a link to a file the download attribute. See Links and navigation for the details.

Groups

src/routes.ts
export const routes = defineRoutes({
  '/(marketing)': {
    layout: MarketingLayout,
    children: {
      '/': Home,
      '/pricing': Pricing,
    },
  },
  '/(docs)': {
    layout: DocsLayout,
    children: { '/guide': Guide },
  },
});

A /(name) key is a group. It wraps the pages below it in a layout but adds nothing to the path: /pricing renders inside MarketingLayout and /guide inside DocsLayout.

Use a group when two sets of pages at the same depth need different layouts. An object can hold the / key only once, so two / objects cannot sit side by side.

Match order

ts
defineRoutes({
  '/products/:id': ProductPage,
  '/products/new': NewProduct,
This pattern is never chosen
});

Matching walks the table from the top and takes the first pattern that fits. No rule prefers the more specific pattern: the order you wrote is the precedence. In this order, /products/new matches /products/:id too, so ProductPage renders with id set to 'new'.

ts
defineRoutes({
  '/products/new': NewProduct,
  '/products/:id': ProductPage,
});

Write the literal pattern first, and /products/new becomes NewProduct. /* goes last for the same reason.

Paths outside the table

A table without /* leaves some paths unmatched. <Router> does not handle navigation to such a path, so the browser loads the page normally and shows the server’s 404.

When the app opens at a path outside the table, <Router> renders nothing.

Rejected patterns

The route table is checked when defineRoutes runs, so a mistake shows up as soon as the app starts. Every error is a TypeError.

  • A key that does not start with /route pattern "products" must start with "/"
  • Parentheses that are not exactly a group, such as /(admin)/newroute group "/(admin)/new" must be "/(name)" and nothing else — a regular expression is not part of the grammar
  • A group without childrenroute group "/(oops)" must have children
  • The same pattern declared twice, wherever the copies nestroute pattern "/x" is declared twice
  • A pattern URLPattern cannot parse: URLPattern’s own TypeError

Parentheses are refused because URLPattern reads (…) as a regular expression. A group without children would declare its parent’s / page a second time.

k8ordo

React libraries that use Baseline features without holding back.