Developers / Rich Text

Rich Text

Learn how to work with rich text from Prismic.

Prismic provides the tools to write, save, query, and render rich text content.

What is rich text?

Rich text is text that can be formatted in a user interface. Most people are comfortable creating content in a rich text editor. But rich text from an application like Microsoft Word or Google Docs has very complicated encoding that is difficult to work with in a web application.

How does Prismic handle rich text?

Prismic provides a rich text editor that saves the content in a simple data structure designed for web publishing.

With Prismic, content creators can author content in a familiar rich text editor. Then, developers can use Prismic's first-class integration to pull the content into a web app and render it as HTML.

Prismic stores text in a particular JSON format that we call "structured text."

Other content management systems

Some other content management systems store text content as HTML or Markdown, like this:

  • HTML
  • Markdown
HTML
Copy
{
  "blog_post_content": "<div>I started reading <em>Great Expectations</em>!</div>"
}
Markdown
Copy
{
  "blog_post_content": "I started reading _Great Expectations_!"
}

This is not how Prismic stores rich text.

The challenge with HTML and Markdown

HTML or Markdown can be convenient — at first — if your app needs HTML or Markdown. But it can become restrictive. For example, what if you want additional formatting options? Or what happens if you're going to override the default HTML? What if you're going to strip out formatting? If you deliver content as Markdown or HTML, you'll need to retrofit a workaround.

Using structured text

Prismic's structured text is fully portable, future-proof, and extensible. You can customize the structured text with whatever formatting options you need, and you can configure how to handle that formatting in your app. The editor experience feels just like any other text editor. The only difference is that the content is saved as a logical data structure rather than an opaque text block.

Here's what rich text looks like on the Prismic Rest API:

Copy
"example_rich_text": [
  {
    "type": "paragraph",
    "text": "I started reading Great Expectations!",
    "spans": [
      {
        "start": 18,
        "end": 36,
        "type": "em"
      }
    ]
  }
]

When you fetch content from the Prismic API, you cannot immediately inject it into your web app. First, you must process it with one of Prismic's open-source packages.

Deeper learning: What is the structured text syntax?

Structured text is presented as an array. Each item in the array is a block of text (a block-level element like a heading, paragraph, or preformatted). Each item contains the raw text string, a block type, and some meta-information describing the text. The meta-information will describe the inline elements, like emphasis, strong, and links.

Our open-source packages provide helpers for converting structure text to HTML or plain text. They also include methods for customizing the output; for example, you could choose to render emphasis elements with <mark> instead of <em>.

You can also manipulate the structured text array to customize your output in advanced implementations. For instance, you could render only the first item in the array or only heading elements.

Using HTML or Markdown

It is still possible to edit and publish HTML and Markdown with Prismic. To do so, configure a rich text field with only the pre-element enabled. Your content editors will see a monospace editor. Use the helper methods from Prismic's open-source packages to convert the field to plain text in your app. Then, you'll have basic HTML or Markdown, which you can use as needed in your app.

What are the key text and title fields?

There are three text fields available for the Prismic editor:

  • Rich text
  • Titles
  • Key text

Key text is the only field that does not use structured text. It is for short, unformatted text. In the JSON API response, key text is delivered as a simple primitive string:

Copy
{
  "example_key_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
}

The rich text and title fields are both structured text. The title field has two unique restrictions:

  • The element must be a heading
  • It only allows one block of text

The rich text field has no restrictions.

Use key text for a simple piece of metadata, such as key terms. Use the title field for titles and headings and the rich text for blocks of text.

Write and edit rich text

Rich text fields work like many other text inputs with formatting capabilities, including bolding, italicizing, and linking functionality. To learn more, read Edit Rich Text.

Model rich text

You can customize the rich text field that appears in the Prismic Editor with the following element types:

  • Heading elements (h1, h2, h3, h4, h5, h6)
  • Normal text paragraph
  • Strong or bold text
  • Emphasized or italic text
  • Preformatted text
  • Inline hyperlink to the web, to a document, or a media item
  • Image
  • Embed to a service URL supporting oEmbed
  • Unordered list
  • Ordered list
  • Right-to-left text
  • Custom labels

For special formatting in your rich text or title fields, you can add custom formatting by using labels. For example, the Prismic kits for developing Prismic apps with JavaScript will, by default, render a custom label as a <span> with a class of the label's name. (This is an advanced configuration that can only be set up in the JSON editor.) Here is an example of a rich text field with the label options “right-align” and "center-align":

Copy
{
  "example_rich_text": {
    "type": "StructuredText",
    "config": {
      "single": "paragraph",
      "label": "Rich Content",
      "placeholder": "Rich Content",
      "labels": ["right-align", "center-align"]
    }
  }
}

Render rich text

Here's what rich text from the Prismic API looks like:

Copy
// API response example of a rich text field
{
  //...
  "example_rich_text": {
    "type": "StructuredText",
    "config": {
      "single": "paragraph",
      "label": "Rich Content",
      "placeholder": "Rich Content",
      "labels": [
        "right-align",
        "center-align"
      ]
    }
  }
}

In your new React application, open slices/Text/index.js. This is the React component for your Text Slices. Your text is rendered by the <PrismicRichText> component.

You can provide your own components to override <PrismicRichText>'s default rendering. The following code will render paragraph elements as blockquotes rather than ps:

Copy
import { PrismicRichText } from "@prismicio/react"

<PrismicRichText
  field={slice.primary.text}
  components={{
    paragraph: ({ children }) => <blockquote>{children}</blockquote>,
  }}
/>

Learn more about providing your own components.

Learn more about how to render rich text in Template Content in React.

Query rich text

To access the rich text of a document, fetch the document from the API. You can see a Prismic API query in src/Page.jsx:

Copy
const [page, { state }] = usePrismicDocumentByUID("page", uid);

This line fetches a document based on its unique identifier — or uid.

You can search API results by rich text using three filters:

  • fulltext to search for documents that contain a given string
  • has to search for documents where a rich text field is populated with content
  • missing to search for documents where a rich text field is not populated with content

Note: has and missing don't work with fields in Slices or groups.

Here’s a fulltext query:

Copy
const [page, { state }] = usePrismicDocumentByUID('page', uid, {
  filters: [prismic.filter.fulltext('document', 'Hello')],
})

To learn more about querying, read Fetch Data in React.

Was this article helpful?
Not really
Yes, Thanks

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.