Master Netlify CMS Editor Components: Create a Custom Editor Widget


Aug 23, 2021

⏱ 3 minute read

Developers can build an editor-friendly custom Editor Component in Netlify CMS that can handle a range of content or media needs, that interface directly with Hugo shortcodes.

Developers working in Netlify CMS can now create and configure custom Editor Components with flexible custom attributes. In this article, we’ll develop a custom component with attributes, display it as a component in the editor pane, and render it in the preview pane, just as it would on the front-end. Editor friendly!

Let’s get started. But first:

What is Netlify CMS?

Netlify CMS is an open-source content management solution built on a Git workflow. It is a headless CMS that supports the modern way to build websites and apps — the Jamstack —  and works with many site generator platforms, including Hugo, Gatsby, NextJS, and more.

The Jamstack architecture provides better performance, higher security, increased scalability, and a better developer experience. Now we get a great editor experience, too: Netlify CMS offers an easy-to-use editing interface for content, built as a single-page React app with custom configurable UI widgets and editor plugins.

Let’s build an Editor Component

Let’s see how that works by creating an Editor Component: a custom video component that a Hugo shortcode will support.

Create the video shortcode

For the sake of this article, we will assume a basic knowledge of Hugo shortcodes. You can either use Hugo’s internal video shortcode or develop your own. Add your shortcode to layouts/shortcodes.

Register the shortcode as an Editor Component

Navigate to Netlify CMS (NCMS)’s index.html in your admin folder.

Create a script tag, and add CMS.registerEditorComponent({}) — NCMS by default exposes a global object window.CMS that you can use to create previews, editor plugins, and widgets. registerEditorComponent lets you add a block component to the Markdown editor.

registerEditorComponent has 7 params. From the NCMS Custom Widgets docs, they are:

  1. id: the internal id of the component. For our video component, let’s call this videos.

  2. label: the label of our component in the editor window. Let’s call this Videos.

  3. fields: fields the editor fills out. Note you can add as many as you like, but each must correspond to an NCMS widget. For this example, we only need one field to capture the video link.

  4. pattern: the Regex pattern used to search for instances of this block in the markdown document. Create a regex pattern that matches the Hugo shortcode:

  5. fromBlock: populates the custom widget in the CMS markdown editor. Given an object with one property for each field defined in fields, return the string you want to insert into your markdown. There is only one field within our component, so let’s assign that to a variable named link:

  6. toBlock: serializes the data from the custom editor component to the markdown editor. Now we can take the link variable created in the previous step and combine it with our shortcode defined in our pattern like so:

    Note well: pattern and toBlock must be identical, aside from the variable replacement.

  7. toPreview: Preview output for this component. It can be a string or a React Component. Ignore the Tailwind classes shown below:

Here is the completed code:

That’s it!

When you refresh the CMS, the custom Video Editor Component will render within the markdown editor on the left, thanks to the toBlock:

And thanks to the toPreview, the component will be rendered and executed in NCMS’s preview pane on the right. Here, we added another field to capture optional captions below a video:

We’d love to hear about your experiences creating custom editor components. Let us know!