Documentation
Custom React Component
On this page
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
- Content editors add a "Custom React Component" block in the wisp CMS editor, specifying the component name and props.
- This creates a custom
<div>
element in the blog content, which is passed via the API. - 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",
],
},