Route table
Write the route table with defineRoutes and decide which page each path becomes.
On this page
Pages and layouts
src/routes.tsexport 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.
Note
The object can also hold error and loading. See Errors and loading for how to write them.
Path params
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/'); // nullA :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.
/*
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).
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.tsexport 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
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'.
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 nest
route pattern "/x" is declared twice - A pattern
URLPatterncannot parse:URLPattern’s ownTypeError
Parentheses are refused because URLPattern reads (…) as a regular expression. A group without children would declare its parent’s / page a second time.