Route Resolver
Learn what the route resolver is and how to use it in your project.
Prismic generates URLs for your web pages using the route resolver.
The route resolver is an option that you can include when initializing an API client or sending an API request. It describes how Prismic should generate URLs for each document in your repository. These URLs are then included for each document and each internal link in your repository in the API response. If no route resolver is specified, the url property will be null.
The route resolver can use data from parent and grandparent documents, allowing you to build complex URLs like boutique.com/clothing/tops/red-blouse.
The route resolver's implementation varies by framework. In some cases, you can include it in your project configuration file. In others, you include it in your client instantiation. For more information, see the documentation for your framework.
In all cases, the route resolver is an array of route objects. Each route object can include the following properties:
- A
pathproperty to describe the URL - Conditions like
langandtypeto describe what documents to apply to - A
resolversproperty to describe content relationships that you want to use in the URL
Let's break that down with an example.
In this example, we have an international clothing boutique. The following route resolver array will describe the routes for a homepage and some product pages:
[
{
type: 'page',
uid: 'homepage',
lang: 'en-us',
path: '/',
},
{
type: 'page',
uid: 'accueil',
lang: 'fr-fr',
path: '/accueil',
},
{
type: 'product',
resolvers: {
category: 'category',
},
path: '/:lang/:category/:uid',
},
{
type: 'product',
resolvers: {
category: 'category',
section: 'category.section',
},
path: '/:lang/:section/:category/:uid',
}
]
The first route object says that if the document is a page with the UID homepage and the locale en-us, then return the root route, /.
The second route object says that if the document is a page with the UID accueil and the locale fr-fr, then return the route /accueil.
The third route object describes the route for a product document. It defines the category resolver, so the URL can access the UID of the category content relationship. Then the route resolver constructs a URL using the locale, the category, and the document's UID. So, for example, the document for a red dress might have the route /en-us/women/red-dress, while the French translation of that document might be /fr-fr/femmes/robe-rouge.
The fourth route object describes the route for a product document. It defines the section and category resolvers, so the URL can access the section (from a grandparent document), the category (from a parent document), and the UID. Then the route resolver constructs a URL using the locale, the section, the category, and the document's UID. So, for example, the document for a red blouse with a parent category of tops and the parent category’s section of clothing, might have the route /en-us/clothing/tops/red-blouse, while the French translation of that document might be /fr-fr/vetements/chemises/chemisier-rouge.
The route resolver is an API Option. To use it in an HTTP request, remove whitespace, encode the value, and, append it to the HTTP URL as described in the Document API Technical Reference.
To use the route resolver with one of our development kits, like JavaScript, React, or Vue, see the documentation for your framework.
Only the path property is required; all others are optional.
The API ID for a specific custom type.
Either the UID for a specific document or * for any document.
Either a specific locale code or * for any locale.
The resolvers property is an object that defines parent and grandparent relationships that can be used as variables in the path property. Resolvers can access parent and grandparent properties. Resolvers cannot access great-grandparents or further.
:uid
The document’s UID.
:lang
The document’s locale code. If flagged as optional with a question mark (:lang?) this segment will be omitted for the master locale.
:resolver
Any resolver variable defined in the resolvers property, such as :state and :country in the example above. If marked as optional with a question mark (:resolver?) the segment will be omitted if it is not available.
The route resolver may fail to address advanced use-cases, like advanced conditions or URL formatting. In those cases, we provide a workaround called a link resolver. The link resolver is a user-defined function. It runs client-side. It accepts a document object and returns the route for that document as a string.
An example of a link resolver that uses a document's first_publication_date property might look like this:
function linkResolver(doc) {
if (doc.type === 'blog_post') {
const date = new Date(doc.first_publication_date)
return `/${date.getFullYear()}/${doc.uid}`
}
return null
}
If your project includes both a link resolver and a route resolver, the link resolver will take priority. Where the link resolver returns null, the route resolver will be used.
The @prismicio/client package has two templating functions that accept a linkResolver parameter: asHTML() and asLink(). Provide your link resolver function as the second parameter:
prismic.asHTML(text, { linkResolver })
prismic.asLink(link, { linkResolver })For more information on how to use these functions, see the @prismicio/client Technical Reference.
Was this article helpful?
Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.