Rich Text and Title Field Reference
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.
Prismic stores text in a particular JSON format that we call "structured text."
Some other content management systems store text content as HTML or Markdown, like this:
- HTML
- Markdown
"blog_post_content": "<div>I started reading <em>Great Expectations</em>!</div>""blog_post_content": "I started reading _Great Expectations_!"This is not how Prismic stores Rich Text.
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.
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:
"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. We provide packages to process, format, and customize the 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>.
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.
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.
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:
"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.
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.
These are all the elements and styles available for the Rich Text field.
- 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":
"example_rich_text": {
"type": "StructuredText",
"config": {
"single": "paragraph",
"label": "Rich Content",
"placeholder": "Rich Content",
"labels": ["right-align", "center-align"]
}
}
The Rich Text field allows content writers to edit rich content with standard formatting options, such as bold, italics, headings, and lists.
You'll see all these available options when configuring a Rich Text field, as well as the Field name, API ID, and Field placeholder.
Slice Machine vs. Legacy Editor
Editing fields is almost identical in Slice Machine and the Legacy editor. But it is important to know that the mock config option (to add data to preview content fields in the Slice Simulator) is only available in Slice Machine.
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_rich_text": {
"type": "StructuredText",
"config": {
"single": "paragraph, strong, em",
"label": "Quote",
"placeholder": "Enter a quote..."
}
}Here is an API response example of a Rich Text field with the API ID of example_rich_text:
// 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"
]
}
}
}
You'll see all the available heading options when configuring a Title field, as well as the Field name, API ID, and Field placeholder.
Slice Machine vs. Legacy Editor
Editing fields is almost identical in Slice Machine and the Legacy editor. But it is important to know that the Mock config option to add data to preview content fields in the Slice Simulator is only available in Slice Machine.
Edit the JSON model with caution
Only edit the JSON model to make changes to the Rich Text field labels. Making abrupt changes can cause conflicts when synchronizing changes with your documents.
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_title": {
"type": "StructuredText",
"config": {
"single": "heading1, heading2, heading3",
"label": "Page Title",
"placeholder": "Enter page title...",
"useAsTitle": true
}
}// API response example of a Title field
{
//...
"example_title":[
{
"type":"heading1",
"text":"Lorem ipsum",
"spans":[]
}
]
}Was this article helpful?
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.