Configure the Rich Text and Title Fields

This article explains how to configure the Rich Text and Title fields, the differences between them, and how they differ from the Key Text field.


How does Prismic handle text?

Text in Prismic is stored in a special JSON format that we call "structured text," which can look a little strange at first.

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 want to override the default HTML? What if you want to strip out formatting? If your content is delivered 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 structured text with whatever formatting options you need, and you can configure how to handle those formattings 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 as an opaque block of text.

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"
      }
    ]
  }
]

This means that 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. We provide packages to process, format, and customize structured text in most major web development languages and frameworks. For more information, see the documentation for your technology.

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>.

In advanced implementations, you can also manipulate the structured text array to customize your output. 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. In your app, use the helper methods from Prismic's open source packages to convert the field to plain text. Then, you'll have plain HTML or Markdown, which you can use as needed in your app.

What are the Rich Text, 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 pieces of metadata, such as key terms. Use the Title field for titles and headings. And use Rich Text for blocks of text.

To learn how to use the Rich Text and Title editors, visit the content creation section. To learn how to render Rich Text and Titles, see the documentation for your framework or technology.

Elements and styles

These are all the elements and styles available for the Rich Text field. Note that for the Title field, only the heading elements and custom labels are available.

  • 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

Custom labels

For special formatting in your Rich Text or Title fields, you can add custom formatting by using labels. For example, the prismic-dom kit 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"]
   }
}

Rich Text field configuration

Screenshot of the Rich Text field in the drag-and-drop editor.

The Rich Text field allows content writers to edit rich content with standard formatting options, such as bold, italics, headings, and lists.

The visual builder

You'll see all these available options when configuring a Rich Text field, as well as the Field name, API ID, and Field placeholder.

Screenshot of the Rich Text field editor.

JSON model

The following table displays the JSON configuration options available in the JSON editor.

If the 'Allow multiple paragraphs' option is unchecked in the visual builder, then "multi" will change to "single" in the JSON editor.

If neither "multi" nor "single" are specified in the config object, then the field will allow multiple paragraphs and include all the available formatting options.

type
string (required)

The value must be StructuredText

config

object

Object for the configuration options

config.placeholder

string

Defines a user-friendly placeholder.

config.label

string

Defines the label that shows up for the field in the editor.

config.labels

array

An array of strings to define labels for custom formatting.

config.multi

string

A comma-separated list of formatting options, with paragraph breaks allowed.
Options: paragraph | preformatted | heading1 | heading2 | heading3 | heading4 | heading5 | heading6 | strong | em | hyperlink | image | embed | list-item | o-list-item | rtl

config.single

string

A comma-separated list of formatting options that does not allow line breaks.

Options: paragraph | preformatted | heading1 | heading2 | heading3 | heading4 | heading5 | heading6 | strong | em | hyperlink | image | embed | list-item | o-list-item | rtl

config.imageConstraint

object

Set the width and/or height constraints of any image added to the field. The object has two properties: width and height, with integers as their values, representing the image size in pixels.

Example JSON configuration

The following JSON defines a single paragraph Rich Text field:

Copy
"example_rich_text": {
  "type": "StructuredText",
  "config": {
    "single": "paragraph, strong, em",
    "label": "Quote",
    "placeholder": "Enter a quote..."
  }
}

API response example

Here is an API response example of a Rich Text field with the API ID of example_rich_text:

Copy
"example_rich_text": [
  {
    "type":"paragraph",
    "text":"Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "spans":["..."]
  }
]

Title field configuration

The Title field is a configurable field dedicated to titles and headings.

Screenshot of the Title field in the drag-and-drop editor.

The visual builder

You'll see all the available heading options when configuring a Title field, as well as the Field name, API ID, and Field placeholder.

Screenshot of the Title field editor.

JSON model

The following table explains all the configuration options of a Title field in the JSON editor:

type

string (required)

Value must be StructuredText

config

object

Object for the configuration options

config.placeholder

string

Defines a user-friendly placeholder.

config.label

string

Defines the label that shows up for the field in the editor.

config.labels

array

An array of strings to define labels for custom formatting.

config.single

string

A comma-separated list of formatting options.

Options: heading1 | heading2 | heading3 | heading4 | heading5 | heading6

Example JSON configuration

The following JSON defines a single heading Title field:

Copy
"example_title": {
  "type": "StructuredText",
  "config": {
    "single": "heading1, heading2, heading3",
    "label": "Page Title",
    "placeholder": "Enter page title...",
    "useAsTitle": true
  }
}

API response example

Below you can see an example Title field's API response:

Copy
"example_title":[
  {
    "type":"heading1",
    "text":"Lorem ipsum",
    "spans":[]
  }
]

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.