Create custom inline editing with the Visual Editor API

CloudCannon's Visual Editor API exposes *.createTextEditableRegion(), which makes any supported HTML element directly editable in the Visual Editor page preview. This article covers how to create, configure, and update custom inline editable regions.

This article assumes you know how to initialize the Visual Editor API. For creating a floating Data Panel, read Create a custom Data Panel with the Visual Editor API. For a complete list of API objects and methods, please read our reference documentation on the Visual Editor API.

Custom inline editing#

Custom inline editing lets Team Members change content directly in the page preview. Clicking an element opens a rich text toolbar and makes the element's content editable in place, without opening a separate panel. This is useful for building a live preview experience, where you can update content in context with your webpage design.

Create a text editable region

Calling *.createTextEditableRegion() allows you to make a supported HTML element inline-editable. This function takes three arguments: your HTML element, a callback which fires whenever the content changes and receives the updated content as a string, and an optional configuration object.

const file = api.currentFile(); 
const element = document.querySelector('#hero-heading'); 

const region = await api.createTextEditableRegion( 
  element,
  (content) => { 
    file.data.set({ slug: 'heading', value: content });
  }
);

The region only makes the element editable in the preview. It doesn't write your changes anywhere on its own: not to a field, and not back to the element. That's up to you in the callback. Use *.content.set() for the file body, or *.data.set() for a structured data field. Like any edit, these update the Visual Editor data model and mark the file as having unsaved changes. The Team Member still saves the file as usual.

Configure a text editable region

Passing an options object as the third argument to *.createTextEditableRegion() customizes how CloudCannon treats the region.

elementType tells CloudCannon which family of HTML tags you are editing (⁠text, block, span, image, or link⁠). That choice affects toolbar behavior and validation. If you omit it, CloudCannon guesses from the tag name (for example, h2 as text, div as block⁠).

editableType accepts the same values as elementType (⁠text, block, span, image, or link⁠), or 'content'. As a rule of thumb, set editableType to the same value as elementType, unless you are editing body content, in which case set it to 'content'.

extension tells CloudCannon which format to serialize the edited content to before passing it to your callback, based on a file extension such as '.html' or '.md'. When the content changes, CloudCannon generates a string in that format. Match it to the format of the underlying file the content belongs to, so the serialized string matches that file. You can leave it out for plain content where the format doesn't matter.

You can also pass inputConfig to control which rich text toolbar options are available.

The following shows common HTML elements and their typical elementType. This is not a strict mapping. For example, a p element could be configured as span if you only want to allow inline content:

• text: p, h1–h6, blockquote, li, dd, dt
• block: div, section, article, aside, main, footer, header, nav
• span: span, small, strong, em, i, b, sub, sup, td, th, cite
• image: img
• link: a

const region = await api.createTextEditableRegion( 
  element,
  (content) => { /* handle update */ },
  { 
    elementType: 'text', 
    editableType: 'text', 
    extension: '.html' 
  }
);

The following lists all options accepted by *.createTextEditableRegion():

Update an inline editable region

Calling *.setContent() on the region object returned by *.createTextEditableRegion() allows you to update the content of the editable region programmatically.

region.setContent('<p>New content</p>');