{"id":43786186,"url":"https://github.com/vobyjs/voby-router","last_synced_at":"2026-02-05T19:04:13.553Z","repository":{"id":37000246,"uuid":"489672781","full_name":"vobyjs/voby-router","owner":"vobyjs","description":"The official client-side router.","archived":false,"fork":false,"pushed_at":"2023-09-24T16:28:52.000Z","size":191,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-07T19:20:10.618Z","etag":null,"topics":["client","router","voby"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vobyjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-05-07T12:53:03.000Z","updated_at":"2024-10-15T16:23:01.000Z","dependencies_parsed_at":"2023-01-17T12:16:54.643Z","dependency_job_id":null,"html_url":"https://github.com/vobyjs/voby-router","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/vobyjs/voby-router","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vobyjs%2Fvoby-router","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vobyjs%2Fvoby-router/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vobyjs%2Fvoby-router/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vobyjs%2Fvoby-router/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vobyjs","download_url":"https://codeload.github.com/vobyjs/voby-router/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vobyjs%2Fvoby-router/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29130113,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T18:55:47.139Z","status":"ssl_error","status_checked_at":"2026-02-05T18:55:04.010Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","router","voby"],"created_at":"2026-02-05T19:04:13.478Z","updated_at":"2026-02-05T19:04:13.546Z","avatar_url":"https://github.com/vobyjs.png","language":"TypeScript","funding_links":[],"categories":["First-Party"],"sub_categories":[],"readme":"# Voby Router\n\nThe router for [Voby](https://github.com/vobyjs/voby).\n---\n\nThis is a port of [Solid-App-Router](https://github.com/solidjs/solid-app-router) to voby.\n\nA router lets you change your view based on the URL in the browser. This allows your \"single-page\" application to simulate a traditional multipage site. To use voby router, you specify components called Routes that depend on the value of the URL (the \"path\"), and the router handles the mechanism of swapping them in and out.\n\nVoby router is a universal router for voby - it works whether you're rendering on the client or on the server. It was inspired by and combines paradigms of React Router and the Ember Router. Routes can be defined directly in your app's template using JSX, but you can also pass your route configuration directly as an object. It also supports nested routing, so navigation can change a part of a component, rather than completely replacing it. \n\nUse it freely with suspense, resources, and lazy components. Voby router also allows you to define a data function that loads parallel to the routes ([render-as-you-fetch](https://epicreact.dev/render-as-you-fetch/)).\n\n- [Getting Started](#getting-started)\n  - [Set Up the Router](#set-up-the-router)\n  - [Configure Your Routes](#configure-your-routes)\n- [Create Links to Your Routes](#create-links-to-your-routes)\n- [Dynamic Routes](#dynamic-routes)\n- [Data Functions](#data-functions)\n- [Nested Routes](#nested-routes) \n- [Config Based Routing](#config-based-routing)\n- [Router Primitives](#router-primitives)\n  - [useParams](#useparams)\n  - [useNavigate](#usenavigate)\n  - [useLocation](#uselocation)\n  - [useSearchParams](#usesearchparams)\n  - [useRouteData](#useroutedata)\n  - [useMatch](#usematch)\n  - [useRoutes](#useroutes)\n\n## Getting Started\n\n### Set Up the Router\n\n```sh\n\u003e npm i voby-router\n```\n\nInstall `voby-router`, then wrap your root component with the Router component:\n\n```jsx\nimport { render } from \"voby\";\nimport { Router } from \"voby-router\";\nimport App from \"./App\";\n\nrender(\n  () =\u003e (\n    \u003cRouter\u003e\n      \u003cApp /\u003e\n    \u003c/Router\u003e\n  ),\n  document.getElementById(\"app\")\n);\n```\n\nThis sets up a context so that we can display the routes anywhere in the app.\n\n### Configure Your Routes\n\n`voby-router` allows you to configure your routes using JSX:\n\n1. Use the `Routes` component to specify where the routes should appear in your app.\n\n\n```jsx\nimport { Routes, Route } from \"voby-router\"\n\nexport default function App() {\n  return (\n    \u003c\u003e\n      \u003ch1\u003eMy Site with Lots of Pages\u003c/h1\u003e\n      \u003cRoutes\u003e\n\n      \u003c/Routes\u003e\n    \u003c\u003e\n  )\n}\n```\n\n2. Add each route using the `Route` component, specifying a path and an element to render when the user navigates to that path.\n\n```jsx\nimport { Routes, Route } from \"voby-router\"\n\nimport Home from \"./pages/Home\"\nimport Users from \"./pages/Users\"\n\nexport default function App() {\n  return (\n    \u003c\u003e\n      \u003ch1\u003eMy Site with Lots of Pages\u003c/h1\u003e\n      \u003cRoutes\u003e\n        \u003cRoute path=\"/users\" element={\u003cUsers/\u003e} /\u003e\n        \u003cRoute path=\"/\" element={\u003cHome/\u003e} /\u003e\n        \u003cRoute path=\"/about\" element={\u003cdiv\u003eThis site was made with Voby\u003c/div\u003e} /\u003e\n      \u003c/Routes\u003e\n    \u003c\u003e\n  )\n}\n```\n\n3. Lazy-load route components\n\nThis way, the `Users` and `Home` components will only be loaded if you're navigating to `/users` or `/`, respectively.\n\n```jsx\nimport { lazy } from \"voby\";\nimport { Routes, Route } from \"voby-router\"\nconst Users = lazy(() =\u003e import(\"./pages/Home\"));\nconst Home = lazy(() =\u003e import(\"./pages/Users\"));\n\nexport default function App() {\n  return (\n    \u003c\u003e\n      \u003ch1\u003eMy Site with Lots of Pages\u003c/h1\u003e\n      \u003cRoutes\u003e\n        \u003cRoute path=\"/users\" element={\u003cUsers/\u003e} /\u003e\n        \u003cRoute path=\"/\" element={\u003cHome/\u003e} /\u003e\n        \u003cRoute path=\"/about\" element={\u003cdiv\u003eThis site was made with Voby\u003c/div\u003e} /\u003e\n      \u003c/Routes\u003e\n    \u003c\u003e\n  )\n}\n```\n\n## Create Links to Your Routes\n\nUse the `A` component to create an anchor tag that takes you to a route:\n\n```jsx\nimport { lazy } from \"voby\";\nimport { Routes, Route, A } from \"voby-router\"\nconst Users = lazy(() =\u003e import(\"./pages/Home\"));\nconst Home = lazy(() =\u003e import(\"./pages/Users\"));\n\nexport default function App() {\n  return (\n    \u003c\u003e\n      \u003ch1\u003eMy Site with Lots of Pages\u003c/h1\u003e\n      \u003cnav\u003e\n        \u003cA href=\"/about\"\u003eAbout\u003c/A\u003e\n        \u003cA href=\"/\"\u003eHome\u003c/A\u003e\n      \u003c/nav\u003e\n      \u003cRoutes\u003e\n        \u003cRoute path=\"/users\" element={\u003cUsers/\u003e} /\u003e\n        \u003cRoute path=\"/\" element={\u003cHome/\u003e} /\u003e\n        \u003cRoute path=\"/about\" element={\u003cdiv\u003eThis site was made with Voby\u003c/div\u003e} /\u003e\n      \u003c/Routes\u003e\n    \u003c\u003e\n  )\n}\n```\n\nThe `\u003cA\u003e` tag also has an `active` class if its href matches the current location, and `inactive` otherwise. **Note:** By default matching includes locations that are descendents (eg. href `/users` matches locations `/users` and `/users/123`), use the boolean `end` prop to prevent matching these. This is particularly useful for links to the root route `/` which would match everything.\n\n| prop     | type    | description                                                                                                                                                                              |\n|----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| href     | string  | The path of the route to navigate to. This will be resolved relative to the route that the link is in, but you can preface it with `/` to refer back to the root.                                                                                                                                                    |\n| noScroll | boolean | If true, turn off the default behavior of scrolling to the top of the new page                                                                                                           |\n| replace  | boolean | If true, don't add a new entry to the browser history. (By default, the new page will be added to the browser history, so pressing the back button will take you to the previous route.) |\n| state    | unknown | [Push this value](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) to the history stack when navigating  |\n| inactiveClass | string  | The class to show when the link is inactive (when the current location doesn't match the link) |\n| activeClass | string | The class to show when the link is active                                                                                                        |\n| end  | boolean | If `true`, only considers the link to be active when the curent location matches the `href` exactly; if `false`, check if the current location _starts with_ `href` |\n\n\n### The Navigate Component\n`voby-router` provides a `Navigate` component that works similarly to `A`, but it will _immediately_ navigate to the provided path as soon as the component is rendered. It also uses the `href` prop, but you have the additional option of passing a function to `href` that returns a path to navigate to:\n\n```jsx\nfunction getPath ({navigate, location}) {\n  //navigate is the result of calling useNavigate(); location is the result of calling useLocation(). \n  //You can use those to dynamically determine a path to navigate to\n  return \"/some-path\";\n}\n\n//Navigating to /redirect will redirect you to the result of getPath\n\u003cRoute path=\"/redirect\" element={  \u003cNavigate href={getPath}/\u003e} /\u003e\n```\n\n## Dynamic Routes\n\nIf you don't know the path ahead of time, you might want to treat part of the path as a flexible parameter that is passed on to the component. \n\n```jsx\nimport { lazy } from \"voby\";\nimport { Routes, Route } from \"voby-router\"\nconst Users = lazy(() =\u003e import(\"./pages/Home\"));\nconst Home = lazy(() =\u003e import(\"./pages/Users\"));\nconst Home = lazy(() =\u003e import(\"./pages/User\"));\n\nexport default function App() {\n  return (\n    \u003c\u003e\n      \u003ch1\u003eMy Site with Lots of Pages\u003c/h1\u003e\n      \u003cRoutes\u003e\n        \u003cRoute path=\"/users\" element={\u003cUsers/\u003e} /\u003e\n        \u003cRoute path=\"/users/:id\" element={\u003cUser/\u003e} /\u003e\n        \u003cRoute path=\"/\" element={\u003cHome/\u003e} /\u003e\n        \u003cRoute path=\"/about\" element={\u003cdiv\u003eThis site was made with Voby\u003c/div\u003e} /\u003e\n      \u003c/Routes\u003e\n    \u003c\u003e\n  )\n}\n```\n\nThe colon indicates that `id` can be any string, and as long as the URL fits that pattern, the `User` component will show.\n\nYou can then access that `id` from within a route component with `useParams`:\n\n```jsx\n//async fetching function\nimport { fetchUser } ...\n\nexport default function User () {\n\n  const params = useParams();\n\n  const [userData] = createResource(() =\u003e params.id, fetchUser);\n\n  return \u003cA href={userData.twitter}\u003e{userData.name}\u003c/A\u003e\n}\n```\n\n### Wildcard Routes\n\n`:param` lets you match an arbitrary name at that point in the path. You can use `*` to match any end of the path:\n\n```jsx\n//Matches any path that begins with foo, including foo/, foo/a/, foo/a/b/c\n\u003cRoute path='foo/*' element={\u003cFoo/\u003e}/\u003e\n```\n\nIf you want to expose the wild part of the path to the component as a parameter, you can name it:\n\n```jsx\n\u003cRoute path='foo/*any' element={\u003cdiv\u003e{useParams().any}\u003c/div\u003e}/\u003e\n```\n\nNote that the wildcard token must be the last part of the path; `foo/*any/bar` won't create any routes.\n\n## Data Functions\nIn the [above example](#dynamic-routes), the User component is lazy-loaded and then the data is fetched. With route data functions, we can instead start fetching the data parallel to loading the route, so we can use the data as soon as possible.\n\nTo do this, create a function that fetches and returns the data using `createResource`. Then pass that function to the `data` prop of the `Route` component. \n\n\n```js\nimport { lazy } from \"voby\";\nimport { Route } from \"voby-router\";\nimport { fetchUser } ... \n\nconst User = lazy(() =\u003e import(\"/pages/users/[id].js\"));\n\n//Data function\nfunction UserData({params, location, navigate, data}) {\n  const [user] = createResource(() =\u003e params.id, fetchUser);\n  return user;\n}\n\n//Pass it in the route definition\n\u003cRoute path=\"/users/:id\" element={\u003cUser /\u003e} data={UserData} /\u003e;\n```\n\nWhen the route is loaded, the data function is called, and the result can be accessed by calling `useRouteData()` in the route component.\n\n```jsx\n//pages/users/[id].js\nimport { useRouteData } from 'voby-router';\nexport default function User() {\n  const user = useRouteData();\n  return \u003ch1\u003e{user().name}\u003c/h1\u003e;\n}\n```\n\nAs its only argument, the data function is passed an object that you can use to access route information:\n\n| key       | type                                           | description                                                                                                 |\n|-----------|------------------------------------------------|-------------------------------------------------------------------------------------------------------------|\n| params    | object                                         | The route parameters (same value as calling `useParams()` inside the route component)                       |\n| location  | `{ pathname, search, hash, query, state, key}` | An object that you can use to get more information about the path (corresponds to [`useLocation()`](#uselocation))          |\n| navigate | `(to: string, options?: NavigateOptions) =\u003e void`                        | A function that you can call to navigate to a different route instead (corresponds to [`useNavigate()`](#usenavigate))     |\n| data      | unknown                                        | The data returned by the [parent's](#nested-routes) data function, if any. (Data will pass through any intermediate nesting.) |\n\nA common pattern is to export the data function that corresponds to a route in a dedicated `route.data.js` file. This way, the data function can be imported without loading anything else.\n\n```js\nimport { lazy } from \"voby\";\nimport { Route } from \"voby-router\";\nimport { fetchUser } ... \nimport UserData from \"./pages/users/[id].data.js\";\nconst User = lazy(() =\u003e import(\"/pages/users/[id].js\"));\n\n// In the Route definition\n\u003cRoute path=\"/users/:id\" element={\u003cUser /\u003e} data={UserData} /\u003e;\n```\n\n## Nested Routes\nThe following two route definitions have the same result:\n\n```jsx\n\u003cRoute path=\"/users/:id\" element={\u003cUser/\u003e} /\u003e\n```\n```jsx\n\u003cRoute path=\"/users\"\u003e\n  \u003cRoute path=\"/:id\" element={\u003cUser/\u003e} /\u003e\n\u003c/Route\u003e\n```\n`/users/:id` renders the `\u003cUser/\u003e` component, and `/users/` is an empty route.\n\nOnly leaf Route nodes (innermost `Route` components) are given a route. If you want to make the parent its own route, you have to specify it separately:\n\n```jsx\n//This won't work the way you'd expect\n\u003cRoute path=\"/users\" element={\u003cUsers/\u003e}\u003e\n  \u003cRoute path=\"/:id\" element={\u003cUser/\u003e} /\u003e\n\u003c/Route\u003e\n\n//This works\n\u003cRoute path=\"/users\" element={\u003cUsers/\u003e} /\u003e\n\u003cRoute path=\"/users/:id\" element={\u003cUser/\u003e} /\u003e\n\n//This also works\n\u003cRoute path=\"/users\"\u003e\n  \u003cRoute path=\"/\" element={\u003cUsers/\u003e} /\u003e\n  \u003cRoute path=\"/:id\" element={\u003cUser/\u003e} /\u003e\n\u003c/Route\u003e\n```\n\nYou can also take advantage of nesting by adding a parent element with an `\u003cOutlet/\u003e`.\n```jsx\n\nimport { Outlet } from \"voby-router\";\n\nfunction PageWrapper () {\n  return \u003cdiv\u003e\n    \u003ch1\u003e We love our users! \u003c/h1\u003e\n    \u003cOutlet/\u003e\n    \u003cA href=\"/\"\u003eBack Home\u003c/A\u003e\n  \u003c/div\u003e\n}\n\n\u003cRoute path=\"/users\" element={\u003cPageWrapper/\u003e}\u003e\n  \u003cRoute path=\"/\" element={\u003cUsers/\u003e} /\u003e\n  \u003cRoute path=\"/:id\" element={\u003cUser/\u003e} /\u003e\n\u003c/Route\u003e\n```\nThe routes are still configured the same, but now the route elements will appear inside the parent element where the `\u003cOutlet/\u003e` was declared.\n\nYou can nest indefinitely - just remember that only leaf nodes will become their own routes. In this example, the only route created is `/layer1/layer2`, and it appears as three nested divs.\n\n```jsx\n\u003cRoute path='/' element={\u003cdiv\u003eOnion starts here \u003cOutlet /\u003e\u003c/div\u003e}\u003e\n  \u003cRoute path='layer1' element={\u003cdiv\u003eAnother layer \u003cOutlet /\u003e\u003c/div\u003e}\u003e\n    \u003cRoute path='layer2' element={\u003cdiv\u003eInnermost layer\u003c/div\u003e}\u003e\u003c/Route\u003e\n  \u003c/Route\u003e\n\u003c/Route\u003e\n```\n\nIf you declare a `data` function on a parent and a child, the result of the parent's data function will be passed to the child's data function as the `data` property of the argument, as described in the last section. This works even if it isn't a direct child, because by default every route forwards its parent's data. \n\n## Config Based Routing\n\nYou don't have to use JSX to set up your routes; you can pass an object directly with `useRoutes`:\n\n```jsx\nimport { lazy, render } from \"voby\";\nimport { Router, useRoutes, A } from \"voby-router\";\n\nconst routes = [\n  {\n    path: \"/users\",\n    component: lazy(() =\u003e import(\"/pages/users.js\"))\n  },\n  {\n    path: \"/users/:id\",\n    component: lazy(() =\u003e import(\"/pages/users/[id].js\")),\n    children: [\n      { path: \"/\", component: lazy(() =\u003e import(\"/pages/users/[id]/index.js\")) },\n      { path: \"/settings\", component: lazy(() =\u003e import(\"/pages/users/[id]/settings.js\")) },\n      { path: \"/*all\", component: lazy(() =\u003e import(\"/pages/users/[id]/[...all].js\")) }\n    ]\n  },\n  {\n    path: \"/\",\n    component: lazy(() =\u003e import(\"/pages/index.js\"))\n  },\n  {\n    path: \"/*all\",\n    component: lazy(() =\u003e import(\"/pages/[...all].js\"))\n  }\n];\n\nfunction App() {\n  const Routes = useRoutes(routes);\n  return (\n    \u003c\u003e\n      \u003ch1\u003eAwesome Site\u003c/h1\u003e\n      \u003cA class=\"nav\" href=\"/\"\u003e\n        Home\n      \u003c/A\u003e\n      \u003cA class=\"nav\" href=\"/users\"\u003e\n        Users\n      \u003c/A\u003e\n      \u003cRoutes /\u003e\n    \u003c/\u003e\n  );\n}\n\nrender(\n  () =\u003e (\n    \u003cRouter\u003e\n      \u003cApp /\u003e\n    \u003c/Router\u003e\n  ),\n  document.getElementById(\"app\")\n);\n```\n## Router Primitives\n\nVoby Router provides a number of primitives that read off the Router and Route context.\n\n### useParams\n\nRetrieves an object containing the route path parameters as defined in the Route.\n\n```js\nconst params = useParams();\n\n// fetch user based on the id path parameter\nconst [user] = createResource(() =\u003e params.id, fetchUser);\n```\n\n### useNavigate\n\nRetrieves method to do navigation. The method accepts a path to navigate to and an optional object with the following options:\n\n- resolve (_boolean_, default `true`): resolve the path against the current route\n- replace (_boolean_, default `false`): replace the history entry\n- scroll (_boolean_, default `true`): scroll to top after navigation\n- state (_any_, default `undefined`): pass custom state to `location.state`\n\n__Note:__ The state is serialized using the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) which does not support all object types.\n\n```js\nconst navigate = useNavigate();\n\nif (unauthorized) {\n  navigate(\"/login\", { replace: true });\n}\n```\n\n### useLocation\n\nRetrieves reactive `location` object useful for getting things like `pathname`\n\n```js\nconst location = useLocation();\n\nconst pathname = useComputed(() =\u003e parsePath(location.pathname));\n```\n\n### useSearchParams\n\nRetrieves a tuple containing a reactive object to read the current location's query parameters and a method to update them. The object is a proxy so you must access properties to subscribe to reactive updates. Note values will be strings and property names will retain their casing.\n\nThe setter method accepts an object whose entries will be merged into the current query string. Values `''`, `undefined` and `null` will remove the key from the resulting query string. Updates will behave just like a navigation and the setter accepts the same optional second parameter as `navigate` and auto-scrolling is disabled by default.\n\n```js\nconst [searchParams, setSearchParams] = useSearchParams();\n\nreturn (\n  \u003cdiv\u003e\n    \u003cspan\u003ePage: {searchParams.page}\u003c/span\u003e\n    \u003cbutton onClick={() =\u003e setSearchParams({ page: searchParams.page + 1 })}\u003eNext Page\u003c/button\u003e\n  \u003c/div\u003e\n);\n```\n\n### useRouteData\n\nRetrieves the return value from the data function.\n\n\u003e In previous versions you could use numbers to access parent data. This is no longer supported. Instead the data functions themselves receive the parent data that you can expose through the specific nested routes data.\n\n```js\nconst user = useRouteData();\n\nreturn \u003ch1\u003e{user().name}\u003c/h1\u003e;\n```\n\n### useMatch\n\n`useMatch` takes an accessor that returns the path and creates a Memo that returns match information if the current path matches the provided path. Useful for determining if a given path matches the current route.\n\n```js\nconst match = useMatch(() =\u003e props.href);\n\nreturn \u003cdiv classList={{ active: Boolean(match()) }} /\u003e;\n```\n\n### useRoutes\n\nUsed to define routes via a config object instead of JSX. See [Config Based Routing](#config-based-routing).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvobyjs%2Fvoby-router","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvobyjs%2Fvoby-router","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvobyjs%2Fvoby-router/lists"}