Custom React Component (Beta)

The React Custom Component feature allows editors to add custom content blocks to their pages using the Slash Command feature in our CMS.

---

Overview

The React Custom Component feature allows editors to add custom content blocks to their pages using the Slash Command feature in our CMS. These blocks are replaced by React components on the frontend, enabling more branded experiences and interactivity within the content itself. This documentation will guide you through the process of setting up and rendering these custom React components within your CMS.

How It Works

1. Content editors add a "Custom React Component" block in the wisp CMS editor, specifying the component name and props.
2. This creates a custom <div> element in the blog content, which is passed via the API.
3. Developers use Wisp's React Custom Component SDK to render the custom component by mapping the component name to a React component that can render the block.

Installation

Install Wisp's React Custom Component SDK

First, you need to add the @wisp-cms/react-custom-component package to your project:

npm i @wisp-cms/react-custom-component

Creating Custom React Components

You can create dynamic content blocks that can be rendered using React components. Below is an example of a ComparisonTable component:

const ComparisonTable = ({ variant, pros, cons }) => (
  <div>
    <h3>{variant}</h3>
    <ul>
      {pros.map((pro, index) => (
        <li key={index}>{pro}</li>
      ))}
    </ul>
    <ul>
      {cons.map((con, index) => (
        <li key={index}>{con}</li>
      ))}
    </ul>
  </div>
);

Rendering Custom Components

To integrate the custom React components with your CMS, import the ContentWithCustomComponents from our SDK:

import { ContentWithCustomComponents } from "@wisp-cms/react-custom-component";

Next, map your custom component's name to the actual React component:

<div className="prose prose-lg container max-w-6xl pb-24">
  <ContentWithCustomComponents
    content={content}
    customComponents={{ ComparisonTable }}
  />
</div>

You can register more than one custom component by adding them to the customComponents map in the ContentWithCustomComponents prop.

Insert Custom Components

Now that you've set up the component, you can add the component anywhere within your blog post by inserting a custom component block from anywhere in your editor.

First, launch the Slash Command by typing / on a new line in the editor. You may type react to filter and select the right block quickly:

Next, select the Pencil icon to edit the component:

From there, you will give the component the same name as the one that was registered earlier (ie ComparisonTable). You can also edit the props that you pass to the component directly in the Component Props field:

Note: The Component Props field only accepts valid JSON data. You may click on "Beautify" to check and format the data.

Finally, click on "Update Component" to update the custom component block. Do not forget to save and publish the blog post when you are done editing the entire post!

Common Use Cases

The React Custom Component feature opens up a world of possibilities for enhancing your content. Here are some popular use cases:

• FAQs: Display Frequently Asked Questions in an accordion style for better user experience.
• Comparison Tables: Create interactive tables to compare products, services, or features.
• Call-to-Action (CTA) Blocks: Design eye-catching newsletter signups or lead generation forms.
• Advertisements: Integrate dynamic ad units that can be easily updated or A/B tested.
• Interactive Charts and Graphs: Embed data visualizations that respond to user input.
• Interactive Quizzes: Engage users with interactive quiz components to capture user responses.
• Product Showcases: Build carousel or grid layouts to highlight multiple products.
• Quiz or Survey Elements: Engage readers with interactive quizzes or feedback forms.
• Social Media Feeds: Display live social media content within your articles.
• Calculator Tools: Offer utility calculators relevant to your content (e.g., mortgage calculators for real estate blogs).
• Video Players: Create custom video players with additional features or branding.
• Interactive Timelines: Present historical or project-based information in an engaging format.
• Maps: Embed custom maps with location markers and various interaction options.

These custom components allow you to create a more engaging and interactive experience for your readers while maintaining the flexibility and ease of use of a headless CMS.

Troubleshooting Common Issues

React Component Not Registered

If you see an error message like this:

Fix: Ensure that the component name in the Wisp editor matches exactly the name used in the customComponents prop of ContentWithCustomComponents.

Component Rendering Error

If you encounter a rendering error:

An error boundary has caught the error to prevent it from bubbling up. To resolve this:

• Check that the props defined in the wisp editor match the expected shape of your component.
• Verify that your component's logic correctly handles the provided props.

Missing Custom Component Block

If you're using sanitize-html and the custom component block is missing, it may be because the tags have been removed. To fix this, allow the following tags and attributes in your sanitize-html configuration:

allowedAttributes: {
  ...defaults.allowedAttributes,
  "*": ["style"],
  iframe: ["src", "allowfullscreen", "style"],
  div: [
    "data-name",
    "data-wisp-react-component",
    "data-version",
    "data-props",
  ],
},