diff --git a/docs/guide/pages-routing/overview.md b/docs/guide/pages-routing/overview.md index 68fc06689..bb92f2913 100644 --- a/docs/guide/pages-routing/overview.md +++ b/docs/guide/pages-routing/overview.md @@ -254,17 +254,20 @@ You can also pass URL strings or `URL` instances to these router methods. See [T `router.visit()` updates the page in place for same-origin URLs. `http(s)` URLs on another origin get a full page load, and other schemes such as `javascript:` are rejected. -For dynamic route params, use `useParams()` from the same adapter package: +For dynamic route params, use `useParams()` from the same adapter package. Pass the page's URL pattern as the type argument to type the result: ```tsx +// pages/posts/[id].tsx import { useParams } from '@void/react'; export default function PostPage() { - const { id } = useParams<{ id: string }>(); + const { id } = useParams<'/posts/:id'>(); // { id: string } return

Post {id}

; } ``` +See [Page params](../type-safety.md#page-params) for how patterns are checked. + ### Active links `Link` marks the link to the current page with `aria-current="page"` and `data-void-active`. Use them to style navigation: diff --git a/docs/guide/type-safety.md b/docs/guide/type-safety.md index cec5993c4..bf2f9a917 100644 --- a/docs/guide/type-safety.md +++ b/docs/guide/type-safety.md @@ -141,6 +141,22 @@ routeUrl('/files/:path{.+}', { params: { path: 'docs/get started' } }); // /files/docs/get%20started ``` +### Page params + +Pass a page's URL pattern as the type argument of `useParams()` to type the params it reads. For `pages/users/[id].tsx`, the pattern is `/users/:id`: + +```tsx +import { useParams } from '@void/react'; + +const { id } = useParams<'/users/:id'>(); // id: string +useParams<'/users/:id'>().idd; // Type error: no such param +useParams<'/userz/:id'>(); // Type error: no page matches +``` + +The pattern must be one of your pages; HTTP and WebSocket routes are not accepted. A catch-all page such as `pages/files/[...path].tsx` gives `{ path: string }`. An unnamed catch-all (`[...].tsx`) has no params. + +The pattern is checked by TypeScript only. Pass the pattern of the page the component renders in; without a pattern, `useParams()` returns `Record`. + ### Checked URL strings [`routing.typedRoutes`](../reference/config.md#routing-typedroutes) checks plain URL strings in `Link`'s `href`, `router.visit()`, `router.prefetch()`, `router.flush()`, and `c.rewrite()`. Apps created with `void init` have it on. To turn it on in an existing app: @@ -192,6 +208,7 @@ Route types update with the dev server. For CI or standalone typechecking, run ` | Fetch client | Route paths, HTTP methods, `body`/`query`/`params`, response type | | Navigation | Route patterns and required parameter names and values in `routeUrl()` and destination objects | | Links | With `routing.typedRoutes`, URL strings in `Link`, router methods, and `c.rewrite()` | +| `useParams` | Page patterns and the names of the params they return | | `useForm` | Action URLs, `data` fields, `errors` keys, `reset()` args (including `{ initial: true }`), `params`, `resetOnSuccess` | | `action()` | Action URLs, `data` payload, `params` | diff --git a/docs/reference/api/pages.md b/docs/reference/api/pages.md index ec3857b23..2d8eb00bb 100644 --- a/docs/reference/api/pages.md +++ b/docs/reference/api/pages.md @@ -86,7 +86,7 @@ Imported from `"@void/vue"`. | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Link` | Vue component for SPA navigation. Renders `` for GET, `