---
title: "Routes"
description: "Configure URLs for your Prismic pages using route resolvers."
category: "concepts"
audience: developers
lastUpdated: "2026-09-04T03:43:36.000Z"
---

Prismic generates page URLs, or routes, to match your website's pages using **route resolvers**.

A route resolver is a JSON object containing rules for a [page type](https://prismic.io/docs/content-modeling.md#page-types)'s URLs. They are passed to the Prismic client's [`routes`](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#config-options) option and are sent on every API request.

```ts
import { createClient } from "@prismicio/client";

const client = createClient("example-prismic-repo", {
  routes: [
    // [!code highlight:1]
    { type: "blog_post", path: "/blog/:uid" },
  ],
});

const blogPost = await client.getByUID("blog_post", "my-first-post");

blogPost.url; // => "/blog/my-first-post"
```

The above example defines a route resolver for blog posts. The fetched blog post's UID is `my-first-post` and its URL is `/blog/my-first-post`.

You can provide any number of route resolvers to the `routes` option. Most websites will have one route resolver per [page type](https://prismic.io/docs/content-modeling.md#page-types).

```ts {3-5}
const client = createClient("example-prismic-repo", {
  routes: [
    { type: "homepage", path: "/" },
    { type: "page", path: "/:uid" },
    { type: "blog_post", path: "/blog/:uid" },
  ],
});
```

[Learn more about the `routes` client option](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#config-options)

# Route resolver properties

Route resolvers support the following properties.

| Property             | Type                    | Description                                                                                                                   | Default |
| -------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------- |
| type                 | string                  | The API ID of a page type.                                                                                                    | None    |
| path                 | string                  | The resolved path of the page with optional [keywords](#path-keywords).                                                       | None    |
| resolvers (optional) | Record\<string, string> | A map of custom keywords to API IDs of the content relationships in the route's page.                                         | None    |
| uid (optional)       | string                  | A specific UID to which this route is scoped. The route is only defined for the page whose UID matches the given UID.         | None    |
| lang (optional)      | string                  | A specific language to which this route is scoped. The route is only defined for pages whose locale matches the given locale. | None    |

# Define route resolvers

Define route resolvers based on your project's setup: the [Prismic CLI](https://prismic.io/docs/cli.md) or [Slice Machine](https://prismic.io/docs/slice-machine.md).

* **Prismic CLI:**

  Define route resolvers in the `routes` array of your project's `prismic.config.json`. The Prismic CLI adds a default route for each page type, whether you model in the Type Builder or with CLI commands, and your project's Prismic client reads the array.

  ```json filename=prismic.config.json
  {
    "repositoryName": "example-prismic-repo",
    "routes": [
      { "type": "homepage", "path": "/" },
      { "type": "page", "path": "/:uid" },
      { "type": "blog_post", "path": "/blog/:uid" }
    ]
  }
  ```

  Edit `prismic.config.json` directly to change a route. Your routes must match your framework's file-system routes. See the [Next.js](https://prismic.io/docs/nextjs.md#define-routes), [Nuxt](https://prismic.io/docs/nuxt.md#define-routes), and [SvelteKit](https://prismic.io/docs/sveltekit.md#define-routes) guides for examples.

* **Slice Machine:**

  > We recommend upgrading to the [Type Builder](https://prismic.io/docs/type-builder.md). See the [migration guide](https://prismic.io/docs/type-builder.md#migrate-to-the-type-builder).

  Define route resolvers in a `routes` constant next to your Prismic client:

  * Next.js and SvelteKit: `prismicio.ts`
  * Nuxt: the module's `clientConfig.routes` option in `nuxt.config.ts`

  See the [Next.js](https://prismic.io/docs/nextjs/with-slice-machine.md#define-routes), [Nuxt](https://prismic.io/docs/nuxt/with-slice-machine.md#define-routes), and [SvelteKit](https://prismic.io/docs/sveltekit/with-slice-machine.md#define-routes) guides for examples.

# Path keywords

Keywords in the `path` property are replaced by dynamic values in the API.

The following keywords are available:

| Keyword  | Description                                                                      |
| -------- | -------------------------------------------------------------------------------- |
| `:uid`   | The page's [UID](https://prismic.io/docs/fields/uid.md).                         |
| `:lang`  | The page's locale code (e.g. `fr-fr`).                                           |
| `:lang?` | The page's locale code (e.g. `fr-fr`) when the page is not in the master locale. |

This example route resolver uses keywords to produce a URL like `/fr-fr/blog/my-first-post`:

```json
{
  "type": "blog_post",
  "path": "/:lang?/blog/:uid"
}
```

# Special cases

Route resolvers handle most URL patterns, but some scenarios require additional configuration. Here are common special cases and how to address them.

## Parent-child nested URLs

Use the `resolvers` property to support multiple levels of URL nesting. It allows you to access the [UID](https://prismic.io/docs/fields/uid.md) of a page assigned to a page's [content relationship](https://prismic.io/docs/fields/content-relationship.md) field.

This type of route resolver is used in sites that allow content writers to affect page URLs. For example, using a page's parent or blog post's category is handled using the `resolvers` property.

Up to two levels of nesting is supported.

```json {3-6}
{
  "type": "page",
  "resolvers": {
    "parent": "parent",
    "grandparent": "parent.parent"
  },
  "path": "/:grandparent?/:parent?/:uid"
}
```

**Example URL**: `/about-us/our-team/jane-doe`

The `resolvers` property is an object mapping keyword names of your choosing to a field name. The above example uses these resolvers:

* `:parent?`: Maps to a content relationship field named `parent`.
* `:grandparent?`: Maps to a content relationship named `parent` in `:parent?`'s page.

The `?` character makes the value optional. If a page does not have a page in its `parent` field, for example, the `:parent?` segment is excluded.

## Override a specific UID

To override a page with a specific [page type](https://prismic.io/docs/content-modeling.md#page-type) and [UID](https://prismic.io/docs/fields/uid.md), use the `uid` property.

```json {3}
{
  "type": "page",
  "uid": "my-special-page",
  "path": "/foo"
}
```

The page with the `my-special-page` UID now has a URL of `/foo`.

## Modify a locale code

To modify the locale code in a URL, use the `lang` property to target a specific language. You can provide a `path` property that uses your desired locale code.

```json {3}
{
  "type": "page",
  "lang": "fr-fr",
  "path": "/fr/:uid"
}
```

The custom value, `fr`, takes the place of the `fr-fr` locale code. Note that the `:lang` keyword is not used in the example.

A page in the `fr-fr` locale with the `my-page` UID now resolves to `/fr/my-page`.

## Broken routes

A [link](https://prismic.io/docs/fields/link.md) or [content relationship](https://prismic.io/docs/fields/content-relationship.md) is broken if the field's linked page is archived or deleted. The API does not have a URL to return in this case.

You can provide an explicit URL for these cases to the Prismic client's [`brokenRoutes`](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#config-options) option.

```ts {3}
const client = createClient({
  routes: [{ type: "page", path: "/:uid" }],
  brokenRoute: "/404",
});
```

This example populates all broken links with `/404`.

[Learn more about the `brokenRoute` client option](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#config-options)

In rare cases, route resolvers may not handle your exact needs. You can use a **link resolver** in those cases.

# Link resolver

> **Important**
>
> Always prefer route resolvers. Treat the link resolver as the last option to override route resolvers.

If a complex URL cannot be defined using a route resolver, you can define the URL using a JavaScript function called a **link resolver**.

Link resolvers are used with the [`asLink()`](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#aslink) helper and are not provided to the Prismic client.

```ts {3-7}
import { asLink, LinkResolverFunction } from "@prismicio/client";

const linkResolver: LinkResolverFunction = (link) => {
  if (link.uid?.startsWith("team-")) {
    return `/about-us/our-team/${link.uid}`;
  }
};

const url = asLink(page, { linkResolver });
```

Link resolvers receive a [link](https://prismic.io/docs/fields/link.md) field as an argument and return its resolved URL. If the resolver does not return a value, the client falls back to its route resolvers.

[Learn more about the `asLink` helper](https://prismic.io/docs/technical-reference/prismicio-client/v7.md#aslink)