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.
Text in Prismic is stored in a special JSON format that we call "structured text," which can look a little strange at first.
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 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.
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:
"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.
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.
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 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.
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
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":
"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.
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:
"example_rich_text": [
{
"type":"paragraph",
"text":"Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"spans":["..."]
}
]
You'll see all the available heading options when configuring a Title field, as well as the Field name, API ID, and Field placeholder.
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_title": {
"type": "StructuredText",
"config": {
"single": "heading1, heading2, heading3",
"label": "Page Title",
"placeholder": "Enter page title...",
"useAsTitle": true
}
}"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.