Tutorials

Rendering Contentful Rich Text with Javascript

Contentful offers many tools to help you work with our Rich Text feature. This guide is meant to help put the pieces together and provide resources for learning more. It focuses majorly on Contentful’s client library, rich-text-html-renderer, and rich-text-react-renderer to render your Rich Text fields with HTML.

Prerequisites

You should already have:

  • a space
  • a CDA token
  • at least one content type with a rich text field
  • at least one entry of that content type
  • Node (at least v8) and NPM installed
  • knowledge of installing tools using the command line.

Getting Started

To create a space, check CMA reference. To learn about retrieving tokens, refer to Authentication.

For content using rich text, refer to this Getting Started with Rich Text guide.

What is rich text?

Rich text is a new JSON format for handling complex content structures in a strongly typed manner. It is represented by the rich text field in Contentful.

Working with a rich text property in Contentful JS client libraries

  1. Install the Contentful client library and rich text html renderer:
npm install --save contentful @contentful/rich-text-html-renderer
  1. Use the Contentful client library to retrieve an entry containing rich text
1import * as contentful from 'contentful';
2import { documentToHtmlString } from '@contentful/rich-text-html-renderer';
3
4const client = contentful.createClient({
5  space: '<space_id>',
6  environment: '<environment_id>', // defaults to 'master' if not set
7  accessToken: '<content_delivery_api_key>',
8});
9
10client.getEntry('<entry_id>'); // asynchronous, returns promise
  1. Invoke the rich text html renderer when the entry resolves
1<!DOCTYPE html>
2<html>
3  <head>
4    <script
5      src="https://cdn.jsdelivr.net/npm/contentful@7.0.5/dist/contentful.browser.min.js"
6      charset="utf-8"
7    ></script>
8    <script>
9      var exports = {}; // quick fix because 'exports' is not defined in rich-text bundle below
10    </script>
11    <script
12      src="https://cdn.jsdelivr.net/npm/@contentful/rich-text-html-renderer@12.0.0/dist/rich-text-html-renderer.es5.min.js"
13      charset="utf-8"
14    ></script>
15
16    <script>
17      const client = contentful.createClient({
18        space: '<space_id>',
19        environment: '<environment_id>', // defaults to 'master' if not set
20        accessToken: '<content_delivery_api_key>',
21      });
22
23      client
24        .getEntry('<entry_id>')
25        .then((entry) => {
26          const rawRichTextField = entry.fields.body;
27          return documentToHtmlString(rawRichTextField);
28        })
29        .then((renderedHtml) => {
30          // do something with html, like write to a file
31          console.log(renderedHtml);
32          document.getElementById('rich-text-body').innerHTML = renderedHtml;
33        })
34        .catch((error) => console.log(error));
35    </script>
36  </head>
37  <body>
38    <p>Here is my rendered rich text:</p>
39    <div id="rich-text-body"></div>
40  </body>
41</html>

Customized rendering

The rich text html renderer also accepts custom renderers as optional parameters.

1import { BLOCKS, MARKS } from '@contentful/rich-text-types';
2import { documentToHtmlString } from '@contentful/rich-text-html-renderer';
3
4const document = {
5  nodeType: 'document',
6  data: {},
7  content: [
8    {
9      nodeType: 'paragraph',
10      data: {},
11      content: [
12        {
13          nodeType: 'text',
14          value: 'Hello',
15          data: {},
16          marks: [{ type: 'bold' }],
17        },
18        {
19          nodeType: 'text',
20          value: ' world!',
21          data: {},
22          marks: [{ type: 'italic' }],
23        },
24      ],
25    },
26  ],
27};
28
29const options = {
30  renderMark: {
31    [MARKS.BOLD]: (text) => `<custom-bold>${text}<custom-bold>`,
32  },
33  renderNode: {
34    [BLOCKS.PARAGRAPH]: (node, next) =>
35      `<custom-paragraph>${next(node.content)}</custom-paragraph>`,
36  },
37};
38
39documentToHtmlString(document, options);
40// -> <custom-paragraph><custom-bold>Hello</custom-bold><u> world!</u></custom-paragraph>

You can find more examples and a list of accepted custom renderers in the documentation for the html renderer library.

Customized rendering in React

The React renderer as well as html-renderer accepts renderers as optional parameters.

1import React from 'react';
2import ReactDOM from 'react-dom';
3
4import { BLOCKS, MARKS } from '@contentful/rich-text-types';
5import { documentToReactComponents } from '@contentful/rich-text-react-renderer';
6
7const richTextDocument = {
8  nodeType: 'document',
9  data: {},
10  content: [
11    {
12      nodeType: 'paragraph',
13      data: {},
14      content: [
15        {
16          nodeType: 'text',
17          value: 'Hello',
18          data: {},
19          marks: [{ type: 'bold' }],
20        },
21        {
22          nodeType: 'text',
23          value: ' world!',
24          data: {},
25          marks: [{ type: 'italic' }],
26        },
27      ],
28    },
29  ],
30};
31
32const Bold = ({ children }) => <span className="bold">{children}</span>;
33
34const Text = ({ children }) => <p className="align-center">{children}</p>;
35
36const options = {
37  renderMark: {
38    [MARKS.BOLD]: (text) => <Bold>{text}</Bold>,
39  },
40  renderNode: {
41    [BLOCKS.PARAGRAPH]: (node, children) => <Text>{children}</Text>,
42  },
43};
44
45const rootElement = document.getElementById('root');
46ReactDOM.render(
47  documentToReactComponents(richTextDocument, options),
48  rootElement
49);
50
51// -> <p class="align-center"><span class="bold">Hello</span><u> world!</u></p>

You can find more examples in the documentation for the React renderer library.

Migrating from markdown to rich text

If you already have markdown fields, you can use the rich text from markdown package. It automatically converts many specific markdown nodes to rich text, with the option of adding a callback for unsupported nodes. See the documentation for the package for more examples and the list of supported markdown nodes.

Future integrations

You may have noticed all our rich text tools can be found in our github repository for rich text. We plan to add more rich text integrations in the future. They will all be made available in this same, central location.

Next steps