{
  "id": "f27c8afff874da86834295f8",
  "source": "solid:signals",
  "type": "github-document",
  "title": "routing",
  "content": "---\ntitle: Routing\nuse_cases: \u003e-\n  page navigation, url structure, nested layouts, dynamic paths, route\n  organization, site architecture\ntags:\n  - routing\n  - navigation\n  - pages\n  - layouts\n  - dynamic\n  - filesystem\nversion: '1.0'\ndescription: \u003e-\n  Build your SolidStart app with file-based routing. Create pages, nested\n  layouts, and dynamic routes with simple file structure.\n---\n\nRouting serves as a key component of web applications.\nWithin SolidStart, there are two types:\n\n- **UI routes** \u0026mdash; define the user interface in your app\n- **[API routes](/solid-start/building-your-application/api-routes)** \u0026mdash; define the serverless functions in your app\n\nTo read more about API routes, [see the API Routes section.](/solid-start/building-your-application/api-routes)\n\n## Creating new routes\n\nSolidStart uses file based routing which is a way of defining your routes by creating files and folders in your project.\nThis includes your pages and API routes.\n\nSolidStart traverses your `routes` directory, collects all of the routes, and then makes them accessible using the [`\u003cFileRoutes /\u003e`](/solid-start/reference/routing/file-routes).\nThis component will only include your UI routes, not your API routes.\nRather than manually defining each `Route` inside a `Router` component, `\u003cFileRoutes /\u003e` will generate the routes for you based on the file system.\n\nBecause `\u003cFileRoutes /\u003e` returns a routing config object, you can use it with the router of your choice.\nIn this example, we use [`solid-router`](/solid-router):\n\n```tsx {7-9} title=\"app.tsx\"\nimport { Suspense } from \"solid-js\";\nimport { Router } from \"@solidjs/router\";\nimport { FileRoutes } from \"@solidjs/start/router\";\n\nexport default function App() {\n\treturn (\n\t\t\u003cRouter root={(props) =\u003e \u003cSuspense\u003e{props.children}\u003c/Suspense\u003e}\u003e\n\t\t\t\u003cFileRoutes /\u003e\n\t\t\u003c/Router\u003e\n\t);\n}\n```\n\nThe `\u003cRouter /\u003e` component expects a `root` prop which functions as the root layout of your entire app.\nYou will want to make sure `props.children` is wrapped in `\u003cSuspense /\u003e` since each component will be lazy-loaded automatically.\nWithout this, you could see some unexpected hydration errors.\n\n`\u003cFileRoutes /\u003e` will generate a route for each file in the `routes` directory and its subdirectories. For a route to be rendered as a page, it must default export a component.\nThis component represents the content that will be rendered when users visit the page:\n\n```tsx title=\"routes/index.tsx\"\nexport default function Index() {\n\treturn \u003cdiv\u003eWelcome to my site!\u003c/div\u003e;\n}\n```\n\nThis means that all you have to do is create a file in your `routes` folder and SolidStart takes care of everything else needed to make that route available to visit in your application!\n\n## File based routing\n\nEach file in the `routes` directory is treated as a route.\nTo create a new route or page in your application, simply create a new file in the `routes` directory.\nThe file name will be the URL path for the route:\n\n- `example.com/blog` ➜ `/routes/blog.tsx`\n- `example.com/contact` ➜ `/routes/contact.tsx`\n- `example.com/directions` ➜ `/routes/directions.tsx`\n\n### Nested routes\n\nIf you need nested routes, you can create a directory with the name of the preceding route segment, and create new files in that directory:\n\n- `example.com/blog/article-1` ➜ `/routes/blog/article-1.tsx`\n- `example.com/work/job-1` ➜ `/routes/work/job-1.tsx`\n\nWhen a file is named `index`, it will be rendered when there are no additional URL route segments being requested for a matching directory:\n\n- `example.com` ➜ `/routes/index.tsx`\n- `example.com/socials` ➜ `/routes/socials/index.tsx`\n\n### Nested layouts\n\nIf you want to create nested layouts you can create a file with the same name as a route folder.\n\n```jsx {2}\n|-- routes/\n    |-- blog.tsx                   // layout file\n    |-- blog/\n        |-- article-1.tsx         // example.com/blog/article-1\n        |-- article-2.tsx        // example.com/blog/article-2\n```\n\nIn this case, the `blog.tsx` file will act as a layout for the articles in the `blog` folder.\nYou can reference the child's content\nby using `props.children` in the layout.\n\n```tsx tab title=\"TypeScript\"\n// routes/blog.tsx\nimport { RouteSectionProps } from \"@solidjs/router\";\n\nexport default function BlogLayout(props: RouteSectionProps) {\n\treturn \u003cdiv\u003e{props.children}\u003c/div\u003e;\n}\n```\n\n```jsx tab title=\"JavaScript\"\n// routes/blog.jsx\nexport default function BlogLayout(props) {\n\treturn \u003cdiv\u003e{props.children}\u003c/div\u003e;\n}\n```\n\n**Note**: Creating a `blog/index.tsx` or `blog/(blogIndex).tsx` is not the same as it would only be used for the index route.\n\n## Renaming Index\n\nBy default, the component that is rendered for a route comes from the default export of the `index.tsx` file in each folder.\nHowever, this can make it difficult to find the correct `index.tsx` file when searching, since there will be multiple files with that name.\n\nTo avoid this, you can rename the `index.tsx` file to the name of the folder it is in, enclosed in parentheses.\n\nThis way, it will be treated as the default export for that route:\n\n```jsx {9}\n|-- routes/                       // example.com\n    |-- blog/\n        |-- article-1.tsx         // example.com/blog/article-1\n        |-- article-2.tsx\n    |-- work/\n        |-- job-1.tsx             // example.com/work/job-1\n        |-- job-2.tsx\n    |-- socials/\n        |-- (socials).tsx           // example.com/socials\n```\n\n#### Escaping nested routes\n\nWhen you have a path that is nested but wish for it to have a separate Layout, you can escape the nested route by applying a name between `( )`.\nThis will allow you to create a new route that is not nested under the previous route:\n\n```jsx {5-6}\n|-- routes/                       // example.com\n    |-- users/\n        |-- index.tsx            // example.com/users\n        |-- projects.tsx         // example.com/users/projects\n    |-- users(details)/\n        |-- [id].tsx            // example.com/users/1\n```\n\nAdditionally, you can incorporate nested layouts of their own:\n\n```tsx {2, 78}\n|-- routes/\n    |-- users.tsx\n    |-- users(details).tsx\n    |-- users/\n        |-- index.tsx\n        |-- projects.tsx\n    |-- users(details)/\n        |-- [id].tsx\n```\n\n### Dynamic routes\n\nDynamic routes are routes that can match any value for one segment of the route.\nWhen your URL path contains a dynamic segment, square brackets (`[]`) are used to define the dynamic segment:\n\n- `example.com/users/:id` ➜ `/routes/users/[id].tsx`\n- `example.com/users/:id/:name` ➜ `/routes/users/[id]/[name].tsx`\n- `example.com/*missing` ➜ `/routes/[...missing].tsx`\n\nThis allows you to create a single route that can match any value for that segment of the URL path.\nFor example, `/users/1` and `/users/2` are both valid routes and rather than defining separate routes for each user, you can use a dynamic route to match any value for the `id` segment.\n\n```tsx {3}\n|-- routes/\n    |-- users/\n        |-- [id].tsx\n```\n\nFor example, using `solid-router`, you could use the [`useParams`](/solid-router/reference/primitives/use-params) primitive to match the dynamic segment:\n\n```tsx title=\"routes/users/[id].tsx\"\nimport { useParams } from \"@solidjs/router\";\n\nexport default function UserPage() {\n\tconst params = useParams();\n\treturn \u003cdiv\u003eUser {params.id}\u003c/div\u003e;\n}\n```\n\n#### Optional parameter\n\nIf you have optional parameters in your route, you can use the double square brackets (`[[id]]`) to define the dynamic segment.\nThis will match a route with or without a parameter.\n\n```tsx {3}\n|-- routes/\n    |-- users/\n        |-- [[id]].tsx\n```\n\nIn this case, some pages that could be matched include:\n\n- `/users`\n- `/users/1`\n- `/users/abc`\n\n#### Catch-all routes\n\nCatch-all routes are a special type of dynamic route that can match any number of segments.\nThey are defined using square brackets with `...` before the label for the route (e.g. `[...post]`).\n\n```tsx {4}\n|-- routes/\n    |-- blog/\n        |-- index.tsx\n        |-- [...post].tsx\n```\n\nA catch-all route will have one parameter which is a forward-slash delimited string of all the URL segments after the last valid segment.\nFor example, with the route `[...post]` and a URL path of `/post/foo` the `params` object returned from the `useParams` primitive will have a `post` property with the value of `post/foo`.\nFor a URL path of `/post/foo/baz` it will be `post/foo/baz`.\n\n```tsx title=\"routes/blog/[...post].tsx\"\nimport { useParams } from \"@solidjs/router\";\n\nexport default function BlogPage() {\n\tconst params = useParams();\n\treturn \u003cdiv\u003eBlog {params.post}\u003c/div\u003e;\n}\n```\n\n## Route groups\n\nUsing route groups, you can organize your routes in a way that makes sense for your application, without affecting the URL structure.\nSince file-based routing is based on the file system, it can be difficult to organize your routes in a way that makes sense for your application.\n\nIn SolidStart, route groups are defined by using parenthesis (`()`) surrounding the folder name:\n\n```tsx {2}\n|-- routes/\n    |-- (static)\n        |-- about-us                // example.com/about-us\n            |-- index.tsx\n        |-- contact-us              // example.com/contact-us\n            |-- index.tsx\n```\n\n## Additional route config\n\nSolidStart offers a way to add additional route configuration outside of the file system.\nSince SolidStart supports the use of other routers, you can use the `route` export provided by `\u003cFileRoutes /\u003e` to define the route configuration for the router of your choice.\n\n```jsx tab title=\"TypeScript\" {3-7}\nimport type { RouteSectionProps, RouteDefinition } from \"@solidjs/router\";\n\nexport const route = {\n  preload() {\n    // define preload function\n  }\n} satisfies RouteDefinition\n\nexport default function UsersLayout(props: RouteSectionProps) {\n  return (\n    \u003cdiv\u003e\n      \u003ch1\u003eUsers\u003c/h1\u003e\n      {props.children}\n    \u003c/div\u003e\n  );\n}\n```\n\n```jsx tab title=\"JavaScript\" {3-7}\nexport const route = {\n  preload() {\n    // define preload function\n  }\n};\n\nexport default function UsersLayout(props) {\n  return (\n    \u003cdiv\u003e\n      \u003ch1\u003eUsers\u003c/h1\u003e\n      {props.children}\n    \u003c/div\u003e\n  );\n}\n```\n\n[api-routes]: /core-concepts/api-routes\n[fileroutes]: /api/FileRoutes",
  "url": "https://github.com/solidjs/solid-docs/blob/HEAD/src/routes/solid-start/building-your-application/routing.mdx",
  "metadata": {
    "path": "src/routes/solid-start/building-your-application/routing.mdx",
    "repo": "solidjs/solid-docs",
    "repo_url": "https://github.com/solidjs/solid-docs.git",
    "size": 10136,
    "source_type": "github"
  },
  "hash": "56811c6f41464763716ae86dc94edc5259ec49b5130436fe503861a2b3c68b5b",
  "timestamp": "2026-02-23T11:43:00.193992847+01:00"
}