{"id":13683542,"url":"https://github.com/anthonyshort/use-next-route","last_synced_at":"2025-04-14T02:31:38.443Z","repository":{"id":66565302,"uuid":"173619783","full_name":"anthonyshort/use-next-route","owner":"anthonyshort","description":"React hook for easy routing within a Next.js app","archived":false,"fork":false,"pushed_at":"2019-03-06T20:21:07.000Z","size":85,"stargazers_count":74,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-27T16:49:30.333Z","etag":null,"topics":["hooks","nextjs","react","routing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anthonyshort.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-03-03T19:25:43.000Z","updated_at":"2024-03-28T14:48:13.000Z","dependencies_parsed_at":"2023-02-22T16:15:27.142Z","dependency_job_id":null,"html_url":"https://github.com/anthonyshort/use-next-route","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonyshort%2Fuse-next-route","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonyshort%2Fuse-next-route/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonyshort%2Fuse-next-route/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonyshort%2Fuse-next-route/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anthonyshort","download_url":"https://codeload.github.com/anthonyshort/use-next-route/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248810883,"owners_count":21165195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["hooks","nextjs","react","routing"],"created_at":"2024-08-02T13:02:14.984Z","updated_at":"2025-04-14T02:31:37.466Z","avatar_url":"https://github.com/anthonyshort.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# use-next-route\n\nReact hook for easy routing within a Next.js app. \n\n```ts\n\nimport { useRoute } from 'use-next-route'\n\nfunction ProjectsLink() {\n  const { bind } = useRoute('/projects')\n  return (\n    \u003ca {...bind}\u003eProjects\u003c/a\u003e\n  )\n}\n```\n\n## Why\n\n* As a Next app grows it becomes hard to manage link to all of the different routes. \n* The `next/link` component has an awkward API that was designed pre-hooks.\n* The router and link also don't have a concept of a \"prefix\", which is required when mounting a Next app in a sub-directory. \n\n## Setup\n\nYou'll need to use `RouteContext` to provide the router and an optional `routePrefix` to the React app. \n\n```ts\nimport { RouteProvider } from 'use-next-route'\nimport { withRouter } from 'next/router'\n\nfunction ProjectsPage(props) {\n  return (\n    \u003cRouteProvider route={props.router.route} routePrefix=\"/dashboard\"\u003e\n      \u003cdiv\u003eMy Projects\u003c/div\u003e\n    \u003c/RouteProvider\u003e\n  )\n}\n\nexport default withRouter(ProjectsPage)\n```\n\nYou'll most likely want to create a custom `_app` rather than doing this on every page.\n\n#### Sub-directory routing\n\nYou can use the `routePrefix`  prop to automatically as a prefix to all links. This will be provided as the `as` option to the router. You'll want to use this if you're mounting your Next app on a sub-directory, like `https://myapp.com/dashboard`. \n\nThis is similar to the assetPrefix option.\n\n## API\n\n### `useRoute(route: UrlObject | string, options: RouteOptions)`\n\n```ts\nimport { useRoute } from 'use-next-route'\n```\n\nReturns an object with the following properties:\n\n* `href`: URL string for the route. Usually used for adding a `href` attribute to links.\n* `onClick`: This will navigate to the route and handle preventing the default mouse event if needed.\n* `bind`: Object containing `href` and `onClick`. Useful for props spreading.\n* `isActive`: If the current browser location starts with the `href`. Used for active states.\n* `navigate`: Navigate to the route.\n\nYou won't use `next/link` or `next/router` directly anymore. Instead you can use the hooks. \n\n* Buttons: You can use the `onClick` property\n* Links: You can use the `href` property and the `onClick` property. The `href` will make it a valid HTML link, allowing users to open to the link in a new tab/window and making it crawlable. Adding the `onClick` prop will trigger a `Router.push` for you automatically.\n\n#### Types \n##### `UrlObject`\n\n* `pathname`: Absolute path to the Next route\n* `query`: Object of key/value pairs that will be appended to the url as a query string.\n\n##### `RouteOptions`\n\n* `prefetch`: Prefetch the route. This is disabled by default so you need to opt-in\n* `replace`: Uses `replace` instead of `push`. \n* `as`: Allows you to override the url in the location bar. If you're using `routePrefix` this is taken care of for you, but if you want to use a custom alias you can instead. The `routePrefix` will still be applied.\n\n#### Examples:\n\n```ts\nimport { useRoute } from 'use-next-route'\n\nfunction Page() {\n  const { href, onClick } = useRoute('/projects')\n  return (\n    \u003ca href={href} onClick={onClick}\u003eClick me!\u003c/a\u003e\n  )\n}\n\nexport default ProjectPage\n```\n\nEnabling prefetch and replacing instead:\n\n```ts\nimport { useRoute } from 'use-next-route'\n\nfunction Page() {\n  const { href, onClick } = useRoute('/projects', {\n    prefetch: true,\n    replace: true\n  })\n  return (\n    \u003ca href={href} onClick={onClick}\u003eClick me!\u003c/a\u003e\n  )\n}\n\nexport default ProjectPage\n```\n\nUsing a `UrlObject` like when you use `Router.push`:\n\n```ts\nimport { useRoute } from 'use-next-route'\n\nfunction ProjectPage(props) {\n  const projectRoute = useRoute({\n    pathname: '/project/details',\n    query: {\n      id: props.project.id\n    }\n  })\n  return (\n    \u003ca href={projectRoute.href} onClick={projectRoute.onClick}\u003e{props.project.name}\u003c/a\u003e\n  )\n}\n\nexport default ProjectPage\n```\n\nUsing a custom hook:\n\n```ts\nimport { useRoute, RouteOptions } from 'use-next-route'\n\nfunction useProjectRoute(projectId: string, options?: RouteOptions) {\n  return useRoute({\n    pathname: '/project/details',\n    query: {\n      id: projectId\n    }\n  }, options)\n}\n\nfunction ProjectPage(props) {\n  const projectRoute = useProjectRoute(props.project.id, {\n    prefetch: true\n  })\n  return (\n    \u003ca href={projectRoute.href} onClick={projectRoute.onClick}\u003e{props.project.name}\u003c/a\u003e\n  )\n}\n\nexport default ProjectPage\n```\n\nExtracting out the custom hooks into a `routes` file:\n\n```ts\nimport { RouteOptions, useRoute } from 'use-next-route'\n\nexport function useProjectRoute(id, options?: RouteOptions) {\n  const route = {\n    pathname: '/projects',\n    query: {\n      id\n    }\n  }\n  return useRoute(route, options)\n}\n\nexport function useSettingsRoute(options?: RouteOptions) {\n  return useRoute('/settings', options)\n}\n```\n\n```ts\nimport { useProjectRoute, useSettingsRoute } from './routes'\n\nfunction Page({ project }) {\n  const projectRoute = useProjectRoute(project.id, {\n    prefetch: true\n  })\n  const settingsRoute = useSettingsRoute()\n  return (\n    \u003c\u003e\n      \u003ca href={projectRoute.href} onClick={projectRoute.onClick}\u003e{project.name}\u003c/a\u003e\n      \u003ca href={settingsRoute.href} onClick={settingsRoute.onClick}\u003eSettings\u003c/a\u003e\n    \u003c/\u003e\n  )\n}\n```\n\n### `RouteProvider`\n\n```ts\nimport { RouteProvider } from 'use-next-route'\n```\n\nAdd the context to you app to inject the Next router. This is required for `useRoute` to work. \n\n```ts\nimport { RouteProvider } from 'use-next-route'\nimport { withRouter } from 'next/router'\n\nfunction ProjectsPage(props) {\n  return (\n    \u003cRouteProvider route={props.router.route} routePrefix=\"/dashboard\"\u003e\n      \u003cdiv\u003eMy Projects\u003c/div\u003e\n    \u003c/RouteProvider\u003e\n  )\n}\n\nexport default withRouter(ProjectsPage)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthonyshort%2Fuse-next-route","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanthonyshort%2Fuse-next-route","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthonyshort%2Fuse-next-route/lists"}