Was this page helpful?

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 SDK and rich-text-html-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 and retrieve your token, refer to this Getting Started with Contentful guide.

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 SDKs

  1. Install the contentful SDK and rich text html renderer:
npm install --save contentful.js @contentful/rich-text-html-renderer
  1. Use the Contentful SDK to retrieve an entry containing rich text
import * as contentful from 'contentful'
import { documentToHtmlString } from '@contentful/rich-text-html-renderer'


const client = contentful.createClient({
  space: '<space_id>',
  environment: '<environment_id>', // defaults to 'master' if not set
  accessToken: '<content_delivery_api_key>'
})

client.getEntry('<entry_id>') // asynchronous, returns promise
  1. Invoke the rich text html renderer when the entry resolves
<!DOCTYPE html>
<html>
  <head>
    <script
      src="https://unpkg.com/contentful@7.0.5/dist/contentful.browser.min.js"
      charset="utf-8"
    ></script>
    <script> var exports = {} // quick fix because 'exports' is not defined in rich-text bundle below
    </script>
    <script
      src="https://unpkg.com/@contentful/rich-text-html-renderer@12.0.0/dist/rich-text-html-renderer.es5.js"
      charset="utf-8"
    ></script>

    <script>
      const client = contentful.createClient({
        space: "<space_id>",
        environment: "<environment_id>", // defaults to 'master' if not set
        accessToken: "<content_delivery_api_key>"
      });

      client.getEntry('<entry_id>')
        .then(entry => {
          const rawRichTextField = entry.fields.body
          return documentToHtmlString(rawRichTextField)
        })
        .then(renderedHtml => {
          // do something with html, like write to a file
          console.log(renderedHtml)
          document.getElementById("rich-text-body").innerHTML = renderedHtml
        })
        .catch(error => console.log(error))
    </script>
  </head>
  <body>
    <p>Here is my rendered rich text:</p>
    <div id="rich-text-body">
    </div>
  </body>
</html>

Working with custom node types

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

import { BLOCKS, MARKS } from '@contentful/rich-text-types';
import { documentToHtmlString } from '@contentful/rich-text-html-renderer';

const document = {
  nodeType: 'document',
  content: [
    {
      nodeType: 'paragraph',
      content: [
        {
          nodeType: 'text',
          value: 'Hello',
          marks: [{ nodeType: 'bold' }]
        },
        {
          nodeType: 'text',
          value: ' world!',
          marks: [{ nodeType: 'italic' }]
        },
      ],
    },
  ]
};

const options = {
  renderMark: {
    [MARKS.BOLD]: text => `<custom-bold>${text}<custom-bold>`
  },
  renderNode: {
    [BLOCKS.PARAGRAPH]: (node, next) => `<custom-paragraph>${next(node.content)}</custom-paragraph>`
  }
}

documentToHtmlString(document, options);
// -> <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.

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.