Template Content

On this page, you'll learn how to template content from the Prismic API in your Next.js application.

Content from Prismic comes in different types. Some are simple fields, like numbers or booleans. Others are structured fields, like titles, rich text, and links.

Simple field types can be used directly in your application:

The @prismicio/react package includes components for rendering structured fields. To render rich text, for instance, you can use <PrismicRichText>:

To get started, let's look at the structure of the API response.

Prismic's development kits offer three types of API request functions:

Get-single requests, such as getFirst() and getByUID(), which return a single document object.

Get-all requests, such as dangerouslyGetAll() and getAllByType(), which return a results array made up of document objects.

Paginated requests, such as get() and getByType(), which return a results array plus pagination information.

By default, a paginated request will return 20 documents, but you can adjust the page size with the pageSize API option to return up to 100 documents. Get-all requests will run recursively to fetch all matching documents.

In Next.js, you might use that data like this:

Slices are repeatable, rearrangeable content sections. The best practice for working with slices is creating reusable components and passing down the data as props.

On the document object, slices are stored in the slices or body array, like so:

To render slices, use the <SliceZone> component from @prismicio/react by passing an array of slices from the API and a list of React components for each type of slice. In the following example, the components are imported from a library of slices exported from the slices/index.js file.

Each slice component will receive the following props that can be used to display the slice’s content.

• slice: The slice object being rendered.
• index: The index of the slice within the slice zone.
• slices: The list of all slice objects in the slice zone.
• context: Arbitrary data passed to the <SliceZone>'s context prop.

A simple slice component could look like this:

The content for each Prismic field can be a simple primitive value or an object. The simple fields can be injected directly into your app since their value is either a string, a number, or a boolean. Here are the simple fields:

• Color
• Key text
• Number
• Select
• Boolean
• Date
• Timestamp

Here's an example of how to use the number field. You can template the other simple fields similarly.

Retrieving the color field is similar. Here we can see how to do inline styling in React:

The date and timestamp fields from Prismic are strings. The raw response for each of these fields has the following formats:

• Date: YYYY-MM-DD
• Timestamp: YYYY-MM-DDTHH:MM:SS+0000

A package named @prismicio/client provides a function to convert a date or timestamp field from Prismic into a JavaScript date object.

With the client package installed, you can handle date and timestamp fields like in the following example:

The geopoint field is served as an object with two properties: latitude and longitude.

Here is an example of how to retrieve the latitude and longitude coordinates for a geopoint field.

Here's an API response of the embed field:

You can display an embed field using the html property on the response. To render HTML, use React's dangerouslySetInnerHTML prop. Learn more about dangerouslySetInnerHTML() in the React documentation.

The <iframe> may have a default height and width defined by the oEmbed provider. You can style the iframe's height and width in your global CSS:

The image field returns an object with data about the image, including a URL for your image (hosted on Prismic's servers) and alt text.

You can template an image using @prismicio/next's <PrismicNextImage> component. It renders an optimized image using next/image and Prismic’s built-in imgix Image CDN integration.

The component uses the field’s URL, dimensions, and alt text to generate its output.

Images can be transformed using Prismic’s built-in imgix integration and the imgixParams prop. This allows you to resize, crop, recolor, and more. See imgix’s URL API Reference for a full list of available information.

The following example converts the image to grayscale with sat: -100:

Alternatively, images can be templated using one of the following components or helpers. <PrismicNextImage> is recommended for most cases, however.

• <PrismicImage> from @prismicio/react
• asImageSrc(), asImageWidthSrcSet(), or asImagePixelDensitySrcSet() from @prismicio/client

Rich text and titles are delivered in an array that contains information about the text structure. Here's an example of the API response of the rich text field (title fields follow the same format).

To render rich text and title fields as React components, use the <PrismicRichText> component from @prismicio/react.

The <PrismicText> component from @prismicio/react will convert and output the text in the rich text or title field as a string.

The link field renders an internal or external link.

Here's what the content of a link field looks like from the API, depending on the type of content you add. This field has an API ID example_link, the first one links to another document with the UID another-document and the type page, the second one has a web URL, and the third one links to a media item:

For each of those links we considered that it had a Link text property enabled to manage the link label.

You can template a link using @prismicio/next's <PrismicNextLink> component. It renders a link using next/link and automatically resolves internal and external links.

If the link has display text, it will automatically be rendered:

To pull in content from another document, you must fetch that content in your API query using the graphQuery or fetchLinks option.

• First, reference the API ID of the type in your content relationship field.
• Then, the API ID of the field that you want to retrieve.

If you have a page type called blog that includes a content relationship field called example_content_relationship linked to a custom type called author where you want to retrieve a field that has an API ID of author_name, you query it like so:

Once you have adjusted your API query, the linked content will appear in a data object nested in the link or content relationship field:

You can then render that content:

A group field renders an array of content fields. Here's what the API response looks like for a hypothetical group field modeling a nav menu.

To template a group field use a .map() function to loop over the results. Here's a usage example:

In React, a key prop should be given to the outer-most component in the .map() function. Give it a value that will be unique among the group field's items.