Tutorial: Working with Rich Content

Some of the data that the JavaScript SDK returns, such as blog posts and database collection items, contains rich content. Rich content is enhanced text content that can include things like formatted text, link previews, images, and video.

The SDK returns rich content as complex objects. If you’re creating a Headless project with a custom frontend, it can be challenging to render the objects yourself. If you build your frontend using React, you can use the ricos-viewer package from Ricos.js to render rich content objects returned by the SDK. Ricos is an open source product designed for editing and rendering rich content objects. It supports Wix rich content objects.

This tutorial explains how to use Ricos to render the rich content objects returned by the SDK. It includes examples for both the Blog and Data modules.

This process has three steps:

  1. Retrieve your Headless project's rich content using the SDK.
  2. Create a React component that can render rich content objects.
  3. Add the component to your page’s code.

Before you begin

Before getting started, you need:

  • A Wix site or Headless project with either the Wix Blog app installed, or with at least one database collection.
  • A blog post or collection item with rich content. To add rich content to a blog post, use the Blog Post Editor to add things like formatted text or images to a post. Use the CMS to add rich content to your collection.
  • Create an OAuth app for your Headless project. Retrieve your app’s client ID. You’ll need to use it in your code.

Step 1. Retrieve rich content data

The first step in rendering rich content is to retrieve it in your frontend code using the SDK. To do this:

  1. In the terminal, run the following commands to install the necessary SDK packages:

    • SDK: yarn add @wix/sdk
    • Blog (if you’re retrieving Blog content): yarn add @wix/blog
    • Data (if you’re retrieving CMS content): yarn add @wix/data

  2. Create a new file in your project called rich-content-api.js.

  3. At the top of your file, add the following import statements.

    Copy

  4. Create an SDK client by adding the following code to your code file. Fill in the value for your client ID. Adjust the value of modules if you are only working with Blog or CMS:

    Copy

  5. Add a function to your file called getRichContent. This function retrieves the rich content data from your project.

    To retrieve collection items

    Use the SDK Data module’s queryDataItems function to retrieve your project’s CMS items. You can use the query builder to refine your results.

    Example code:

    Copy
    To retrieve blog posts

    Use the SDK Blog module’s queryPosts function to retrieve your project’s blog posts. You can use the query builder to refine your results.

    Example code:

    Copy

Step 2. Create a rich content viewer component

The next step is to create a React component that uses the ricos-viewer package to display rich content objects. The viewer package doesn’t support all the Wix rich content types out of the box. However, Ricos provides plugins for them. Learn more about the plugins in the Ricos documentation.

The viewer generates a React class component with the rendered rich content. This means you can only work with this component in client code. If your project supports React Server Components, make sure to add ’use client’ at the top of your code file.

To create your component, do the following:

  1. Install the ricos-viewer package, its dependencies, and the plugins to support the different Wix rich content types. To do this, run the commands below.
    The commands install the plugins for all the rich content types. If there are some types that you aren’t using in your project, you can leave them out.

    Note: You must use the same version for ricos-viewer and the plugin packages. We recommend major version 9.

    Copy

  2. Create a new file in your project called RichContentViewer.jsx.

  3. Add ’use client’ to the top of the file if needed. See the introduction to this section for details.

  4. Import React, the viewer package, and all the plugins.

    Copy

  5. Create an array of initialized plugin objects. You can modify the way different rich content types are rendered by passing configuration objects to the plugin functions. For more information, see the Ricos documentation.

    Copy

  6. Create a React component called RichContentViewer that accepts content as a prop and returns a RicosViewer component with content and the plugins array from the previous step passed in as props. Export the component.

    Copy

Step 3. Render rich content on a site

The final step is to create a React component that uses the code from the previous sections to retrieve rich content and display it on a page. If you’re working in a framework like Next.js, this component would probably be a React Server Component defined in the code file for a particular page on your site.

To create this component, do the following:

  1. Add the following import statements to your file. Make sure to include the correct paths to your rich-content-api and RichContentViewer files.

    Copy

    toDraft() converts the rich content object received from the SDK into Draft.js format that the Ricos viewer uses.

  2. Create a component called RichContent that uses your getRichContent function to retrieve your content, converts to Draft.js format using toDraft(), and then passes the result to your RichContentViewer component.

    Copy

  3. Export another component called Page that includes your RichContent component. In a real site, this component would likely include other elements of your page.

    Copy

Example code

rich-content-api.js

Copy

RichContentViewer.jsx

Copy

page.jsx

Copy

You now have a basic app that can render rich content using React. For more information about working with the SDK, see the SDK Reference.

Did this help?