Rendering the Rich Text / Title Field

Prismic no longer recommends the gatsby-source-prismic-graphql plugin

With recent changes to Gatsby, Prismic no longer recommends the gatsby-source-prismic-graphql plugin that this documentation uses. Read more about the future of Prismic and Gatsby. We highly recommend using the gatsby-source-prismic instead. The documentation for this plugin can be found in the plugin's github README.

We will leave this documentation here for now, but will change it in the future when we determine the best approach for Prismic & Gatsby.

The Rich Text field is a configurable text field with formatting options. This field provides content writers with a WYSIWYG editor where they can define the text as a header or paragraph, make it bold, add links, etc. The Title field is a specific Rich Text field used for titles. Refer to our User Guides to learn more about the Rich Text and Title fields.

Before Reading

This page assumes that you have retrieved your content and stored it in a variable named document.

It is also assumed that you have included a Link Resolver with the variable name linkResolver in your project. To learn more about this, check out the Link Resolving page.

Rich Text vs Title fields

A Title field is simply a specific version of a Rich Text field. Because of this, they are both rendered the exact same way. There is nothing special you need to do to render one or the other. All the methods outlined in this article will work for both field types. As such, for the rest of the article we will refer to Rich Text fields, but keep in mind that this includes both Rich Text and Title fields.

Render as HTML

The basic usage of the Rich Text / Title field is to use the RichText component to transform the Rich Text content into HTML.

The following is a very simple example that would output the HTML for a Rich Text field that has the API ID of description.

Copy
import React from 'react'
import { RichText } from 'prismic-reactjs'
import { linkResolver } from '@prismicio/gatsby-source-prismic-graphql'

const MyComponent = ({ document }) => (
  <div>
    <RichText
      render={document.description}
      linkResolver={linkResolver}
    />
  </div>
)

export default MyComponent

In the previous example, the RichText component has a linkResolver property where you can pass in a Link Resolver function. This is necessary to provide the correct url for any Link to a Document that exists in your Rich Text content.

Note that you do not need to provide a Link Resolver (for example, you can't include links in a Title field, so you don't need to provide a linkResolver). If you don't provide a Link Resolver, though, any Link to a Document in the Rich Text content won't work properly.

To learn more about how to set up a Link Resolver, check out our Link Resolving page.

Under the hood, the RichText component takes your Rich Text data and serializes it. Based on your data type (ie. heading, paragraph, list, link...), it creates an HTML template and renders it as a React component. Most of the time it's enough, but because we're using Gatsby, you'll probably want to render internal links as Gatsby Link components instead of anchor <a> elements.

We created a property called serializeHyperlink just for this:

Copy
import React from 'react'
import { Link } from 'gatsby'
import { RichText } from 'prismic-reactjs'
import { linkResolver } from '@prismicio/gatsby-source-prismic-graphql'

const GatsbyLink = (type, element, content, children, index) => {
  if (element.data.link_type === 'Document') {
    return (
      <Link to={linkResolver(element.data)} key={element.data.id}>
        {content}
      </Link>
    )
  }
  return null
}

const MyComponent = ({ document }) => (
  <div>
    <RichText
      render={document.description}
      serializeHyperlink={GatsbyLink}
    />
  </div>
)

export default MyComponent

Customizing the HTML output

If serializeHyperlink is not enough, you can customize any aspect of the HTML output by passing an HTML serializer to the RichText component. You can learn more about this on the HTML Serializer page.

Copy
import React from 'react'
import { RichText } from 'prismic-reactjs'
import { htmlSerializer } from './path-to/htmlSerializer.js'

const MyComponent = ({ document }) => (
  <div>
    <RichText
      render={document.description}
      htmlSerializer={htmlSerializer}
    />
  </div>
)

export default MyComponent

Wrapping your Rich Text in a React component

Out of the box, RichText wraps your content in a React.fragment, but you can pass an optional Component property to wrap the Rich Text component in something else. Here's an example where we wrap the Rich Text content in a div element.

Copy
import React from 'react'
import { RichText } from 'prismic-reactjs'

const MyComponent = ({ document }) => (
  <RichText
    render={document.description}
    Component="div"
  />
)

export default MyComponent

Output as plain text

The RichText.asText method will convert and output the text in the Rich Text / Title field as a string.

Here is an example that outputs the Rich Text content as plain text. In this case, the Rich Text field has an API ID of author_name.

Copy
import React from 'react'
import { RichText } from 'prismic-reactjs'

const MyComponent = ({ document }) => (
  <h3 className="author">
    {RichText.asText(document.author_name)}
  </h3>
)

export default MyComponent

A full example

Now let's take a look at a full page component example. Here you can see how the Rich Text field is included in the query, retrieved, and templated on the page. In this example, we'll retrieve two Rich Text / Title fields with the API IDs of page_title and description.

Copy
import React from 'react'
import { graphql, Link } from 'gatsby'
import { RichText } from 'prismic-reactjs'
import { linkResolver } from '@prismicio/gatsby-source-prismic-graphql'

const GatsbyLink = (type, element, content, children, index) => {
  if (element.data.link_type === 'Document') {
    return (
      <Link to={linkResolver(element.data)} key={element.data.id}>
        {content}
      </Link>
    )
  }
  return null
}

const Page = ({ data }) => {
  const prismicContent = data.prismic.allPages.edges[0]
  if (!prismicContent) return null
  const document = prismicContent.node

  return (
    <>
      <h1 className="page-title">
        {RichText.asText(document.page_title)}
      </h1>
      <RichText
        render={document.description}
        serializeHyperlink={GatsbyLink}
      />
    </>
  )
}

export const query = graphql`
query {
  prismic {
    allPages(uid: "example-page") {
      edges {
        node {
          page_title
          description
        }
      }
    }
  }
}
`

export default Page