Template Fields

On this page, you'll learn how to template Prismic content fields in your Gatsby application.


ūüēô Before reading

This page assumes that you have saved the response of your queries in a variable named document and that you've already installed the prismic-reactjs library. You'll use this library to import helper components into your templates, as shown below:

import { Link, RichText } from 'prismic-reactjs'

Intro to templating

Prismic content fields come in more than a dozen types. Most of these are simple primitive values, like Numbers or Booleans. Others are more complex structured values, like Titles, Rich Texts, and Links.

Before starting to template your content, you need to access the retrieved data of the API response. This will depend on whether you've queried for multiple documents or a single one. Then, you might access a single data field like this:

  • Multiple documents
  • Single document
Copy
documents[0].data.example_key_text 
Copy
document.data.example_key_text 

For multiple documents, it's more likely that you would loop over the results array and template each data field, like this:

Copy
<ul>
  {documents.map((item, i) =>{
    <li key={i}>
      {item.data.example_key_text}
    </li>
  })}
</ul>

Simple fields

The fields that are considered simple return primitive values:

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

The Date and Timestamp fields are both delivered as Strings on the API, but they can do a lot more with a little parsing. You can use Gatsby's built-in date and timestamp formatting capabilities.

Templating simple fields is generally simple. If you've already learned how to retrieve fields from a query, the work is almost done. After that, you can inject them directly into your application:

  • Boolean
  • Color
  • Key Text
  • Number
  • Select
  • Date
  • Timestamp
Copy
<span>{document.data.example_boolean}</span>
// Example Boolean outputs as: true 
Copy
<span>{document.data.example_color}</span>
// Example Color outputs as: "#a24196"
Copy
<span>{document.data.example_key_text}</span>
// Example Key Text outputs as: "Lorem ipsum"
Copy
<span>{document.data.example_number}</span>
// Example Number outputs as: 7
Copy
<span>{document.data.example_select}</span>
// Example Select outputs as: "Lorem"
Copy
<span>{document.data.example_date}</span>
// Example Date outputs as: "2023-10-22"
Copy
<span>{document.data.example_timestamp}</span>
// Example Timestamp outputs as: "2023-10-22T05:00:00+0000"

Structured fields

The rest of the fields in Prismic are delivered as objects, so they need to be parsed. Some of them require some more explanation, so they have dedicated articles:

Below, we'll explain how to work with the following structure fields:

  • Timestamp
  • Geopoint
  • Embed
  • Group

Geopoint

The GeoPoint field works by adding coordinates or pasting a Google Maps URL, and it's served as an object with two properties: latitude and longitude. This is the structure of a geopoint response:

Copy
"example_geopoint": {
  "latitude": 48.85392410000001,
  "longitude": 2.2913515000000073
},

You can access these properties directly:

Copy
const lat = document.example_geopoint.latitude   
// Example latitude outputs as: 48.85392410000001

const long = document.example_geopoint.longitude 
// Example longitude outputs as: 2.2913515000000073

Embed

This is the structure of an Embed field:

Copy
"example_embed": {
  "version": "1.0",
  "url": "https://prismic.io",
  "type": "link",
  "title": "Make your website editable for the whole team - Prismic",
  "provider_name": null,
  "thumbnail_url": "https://images.prismic.io/prismic-website/6e49007fec52f99861047cdd55b3ab190ea04295_dev-landing-page-image.png?auto=compress,format",
  "html": "<div data-type=\"unknown\"><a href=\"https://prismic.io\"><h1>Make your website editable for the whole team - Prismic</h1><img src=\"https://images.prismic.io/prismic-website/6e49007fec52f99861047cdd55b3ab190ea04295_dev-landing-page-image.png?auto=compress,format\"><p>Choose your technology. Use the API to fetch content. Empower your content team.</p></a></div>",
  "embed_url": "https://prismic.io/"
},

You can template an Embed field using the html or url values from the response:

Copy
<div dangerouslySetInnerHTML={{ __html: document.example_embed.html }} />

// Example Embed outputs as raw html

Group

A Group field renders an array of content fields:

Copy
"example_group": [
  {
    "example_boolean_in_group": true,
    "example_number_in_group": 3,
    "example_key_text_in_group": "dog"
  },
  {
    "example_boolean_in_group": true,
    "example_number_in_group": 7,
    "example_key_text_in_group": "cat"
  },
],

To template a Group, you can use a map function map() to loop over the results:

Copy
<ul>
  {document.example_group.map((post, i) => (
    <li key={`post-${i}`}>
      {post.example_key_text}
      {post.example_number}
    </li>
  ))}
</ul>

// Example Group outputs as a list of items

Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.