Rich text support

Rich text gives editors control over how text and other elements appear within a component. This could be as simple as allowing inline formatting in the form of bold and italic text effects, or more specialized elements such as block quotes, code blocks, or even images and embedded components.

Example of the Uniform rich text editor UI

Rich text in Uniform#

Most systems distill the formatting from rich text into a proprietary JSON format that's programmatically consumed by your chosen front end, converting the raw data into web-friendly HTML.

Rich text fields can vary dramatically in terms of their function and capabilities. Most systems supporting this formatting will also provide a proprietary package or rendering engine that does the heavy lifting so that rich text works seamlessly when computed into HTML.

Rich text from Uniform or external sources#

An important early decision to make is if you want your editors to create and maintain rich text for a given component within Uniform directly or from an external system. Unlike many parameters in Uniform, the rich text parameter isn't designed to be connected to external data as Uniform can't guarantee that external sources utilise a compatible data structure to the one supported by Uniform's packages.

Uniform's rich text parameter#

Out of the box you will find that Uniform supplies a parameter type called rich text that can be implemented on any component. Once implemented, the parameter will allow you to enter and format rich text directly from within Uniform Canvas.

Add the rich text parameter to a component#

Adding the Uniform rich text parameter to a component is the same as adding any other parameter type. Navigate to the component configuration page for the a component which you would like to support rich text and select Add parameter. Then select the rich text parameter type:

Add the rich text parameter.

Once added, you will be able to control the formatting options that you would like to make available to your editors. This provides necessary governance to prevent authors from using elements that aren't part of the design system (such as block quotes).

Configure the rich text parameter.

Once your new parameter has been saved, configuration is complete. Next, you will need to ensure that your front end is able to process the rich text field, converting it to web-friendly HTML.

Render the Uniform rich text parameter#

Uniform stores any content that's entered into the rich text parameter in a JSON format delivered through Uniform's APIs and compiled into HTML. Below are some ways you can perform this compilation of HTML using the Uniform SDK.

Uniform provides a Vanilla.js-based rich text to HTML renderer as well as components for React and Vue. Each option allows for overriding the way a rich text node is rendered.

There are two types of React or Vue components:

UniformRichText which is given a parameterId. It will look up the value based on a current composition. This is likely to be the simplest way to render rich text fields within the application.
Tthe UniformRichTextNode component which can be given the node data directly.

Uniform also supplies framework-specific components for Next.js and Nuxt. These take care of overriding some nodes which have framework-specific functionality like the link node.

Render a rich text parameter#

Next.js

If you are using Next.js, import the same component from the @uniformdev/canvas-next package to get enhancements based on the framework.

import { UniformRichText } from '@uniformdev/canvas-react' function MyComponent() { return ( <> <h1>My Uniform Component</h1> <UniformRichText parameterId="articleBody" /> </> ) }

Render a rich text node#

Rich text content will look something like this:

const richTextNode = { root: { type: 'root', version: 1, children: [ { type: 'paragraph', version: 1, children: [ { type: 'text', version: 1, text: 'text', }, ], }, ], }, }

import { UniformRichTextNode } from '@uniformdev/canvas-react' function MyComponent() { const richTextNode = { ... } return ( <> <h1>Article</h1> <UniformRichTextNode node={richTextNode} /> </> ) }

Overrides and custom nodes#

You can override internal rich text node renderers as well as provide renderers for custom node types.

import { UniformRichTextNode } from '@uniformdev/canvas-react' function MyParagraphRichTextNode({ node, children }) { return <p class="my-paragraph">{children}</p> } function resolveRichTextRenderer(node) { if (node.type === 'myparagraph') { return MyParagraphRichTextNode } } function MyComponent({ richTextNode }) { return ( <> <h1>Article</h1> <UniformRichTextNode node={richTextNode} resolveRichTextRenderer={resolveRichTextRenderer} /> </> ) }

Rich text from integrations and external sources#

The Uniform rich text parameter is ideal for components leveraging a single piece of content to support an article or campaign. But sometimes you may use structured content from multiple external sources. In these cases, rich text that comes from a system with a data structure different from the one provided by Uniform, which requires slightly different steps to ensure the rich text renders correctly in your frontend.

Connecting external rich text to components#

To consume rich text data in the frontend, you will need to create a parameter to connect to rich text data in the API response from your chosen external source. First, navigate to the component which you would like to support rich text, and add a new parameter of type JSON Data. Give this parameter any name that you like, for example "Rich text content."

The options for adding a JSON parameter to a component.

Once the parameter is configured, you can connect it to any JSON content from external sources. Next, within Canvas, you will create a new data resource which contains rich text content from your integration source. At this stage, you need to select the top-level field which contains the rich text content in JSON format, and connect this data to your component.

Example of connecting Contentful rich text to a JSON parameter

tip

Once you have set up a data connection between a JSON parameter and rich text, Uniform recommends saving this configuration as a pattern to make updating the content easier in the future. To find out more, check out the guide on patterns.

To learn more about connecting data to components, check out the connect external data guide.

Rendering external rich text into HTML#

Once you have connected the JSON rich text data to your component in Canvas, you will need to head to the component on your front end which will resolve the rich text into HTML. Check the documentation for your rich text service, as the steps for processing rich text may vary by front-end framework.

In general, this may involve installing a package from the service that can handle the compilation of HTML from the JSON data that you have already connected to Canvas.

Connecting multiple rich text sources

If you are using a project with multiple integrations, there may be a case where you need to support rich text from multiple sources on the same component. In these cases, Uniform recommends following the same steps as above and to use the frontend to determine the correct package for compiling the resulting JSON data into HTML.

On this page