useParams

Read the dynamic segments of the current route, such as the id in /posts/:id, typed from your app's routes.

import { useParams } from '@gio.js/react';

export function LikeButton() {
  const { id } = useParams<'/posts/:id'>(); // id: string
  return <button onClick={() => void like(id)}>Like</button>;
}

Reference

Type parameter

The hook takes no arguments.

Returns

An object with one string per dynamic segment of the matched route:

A catch-all is one string with its / separators - split it yourself. An optional catch-all that matches no segment is ''; its type is optional (useParams<'/shop/*path?'>() gives { path?: string }), so test it with if (path).

Behavior

• The values are the router's match, the same ones getServerSideProps receives as ctx.params, on the server and in the browser alike.
• After a soft navigation, hydrated components read the new route's params.
• In a not-found.tsx or error.tsx page and its layouts, it returns the params of the route that was not found or failed - {} for a URL no route matches.
• Outside a tree GioJS rendered (a unit test), it returns {}.

Examples

Breadcrumbs from a catch-all route

import { GioLink, useParams } from '@gio.js/react';

export function Breadcrumbs() {
  const { slug } = useParams<'/docs/*slug'>();
  const parts = slug.split('/');
  return (
    <ol>
      {parts.map((part, i) => (
        <li key={i}>
          <GioLink href={'/docs/' + parts.slice(0, i + 1).join('/')}>{decodeURIComponent(part)}</GioLink>
        </li>
      ))}
    </ol>
  );
}

A params shape without typed routes

const { team, project } = useParams<{ team: string; project: string }>();

Good to know

• Values are not decoded: /posts/caf%C3%A9 gives 'caf%C3%A9' (unreserved characters such as %61 are already decoded by the server's path canonicalization). Use decodeURIComponent to show them.
• The pattern names come from the URL shape, so route groups never appear in them: app/(shop)/products/[id] is '/products/:id'.
• Patterns autocomplete, and a pattern that is not one of your routes fails tsc, once .gio/routes.d.ts exists (written at every server start) and is in your tsconfig.json include. Without it, any pattern is accepted and its params are read from the pattern.
• In the server-only root layout the value is that of the page loaded in full: soft navigations do not re-render it.
• A page also receives the params as a prop (PageProps<'/posts/:id'>) when it has no getServerSideProps; the hook saves passing them down.

Related

• Dynamic routes - [id], [...slug] and [[...slug]].
• href - build a URL from a pattern and params.
• TypeScript - typed routes.
• usePathname, useSearchParams.

Version history