Editable Regions

This HTML attribute defines the type of Editable Region that CloudCannon should use in the Visual Editor. You can add this HTML attribute to a DOM element in any file type as long as it outputs to an HTML file after a Site build.

Values can be one of the following: text, image, source, array, array-item, or component.

Depending on the value of this HTML element, the Visual Editor will also require other HTML attributes for Editable Regions to function.

If there is no appropriate DOM element, you can wrap elements in the equivalent web component, which will accept HTML attributes. The web component can be one of the following: <editable-text>, <editable-image>, <editable-source>, <editable-array>, <editable-array-item>, or <editable-component>.

This HTML attribute, or the equivalent web component, is required for all Editable Regions.

<html lang="en">
  <body>
    <main>
      <article>
        <h1 data-editable="text" data-prop="title" >{title}</h1>
      </article>
    </main>
  </body>
</html>

<html lang="en">
  <body>
    <main>
      <article>
        <editable-text data-prop="@content">
          <slot />
        </editable-text>
      </article>
    </main>
  </body>
</html>

This HTML attribute defines the path to the structured data key you want to edit. CloudCannon will pass the value of that key to your Editable Region so the Visual Editor can re-render that section of your webpage preview.

Values can be one of the following: a key from your front matter, @content for the Markdown content of your file, @collections[name].index.key for a key from a specific Collection, @data[filename].key, or @file[path].key for a key from a specific file. You can combine @file[path] with @content to edit the Markdown content of another file (i.e., @file[path].@content⁠).

Array and Array Item Editable Regions also provide two values from the structure of your array, rather than from your data. An Array Editable Region provides @length, the number of items in the array. An Array Item Editable Region provides @index, the position of that item. Reference either value from an Editable Region nested inside, using data-prop or a data-prop-* HTML attribute.

For Image Editable Regions, data-prop can select an object containing the src, alt, and title keys, instead of binding each value with a separate data-prop-* attribute.

This HTML attribute is required for Text and Array Editable Regions.

<html lang="en">
  <body>
    <main>
      <article>
        <h1 data-editable="text" data-prop="title" >{title}</h1>
      </article>
    </main>
  </body>
</html>

---
title: Our new project
author: H. Scott
banner_image: /assets/banner.jpg
date: 2025-08-26T11:17:02+12:00
---
Content goes here.

<html lang="en">
  <body>
    <main>
      <article>
        <editable-text data-prop="@file[about.md].@content">
          <Content />
        </editable-text>
      </article>
    </main>
  </body>
</html>

<ul data-editable="array" data-prop="testimonials">
  {
    testimonials.map((testimonial, index) => (
      <li data-editable="array-item">
        <editable-component
          data-component="testimonial_card"
          data-prop-position="@index"
        >
          <TestimonialCard {...testimonial} position={index} />
        </editable-component>
      </li>
    ))
  }
</ul>

<img
  data-editable="image"
  data-prop="banner"
  src={banner.src}
  alt={banner.alt}
  title={banner.title}
/>

---
title: Our new project
banner:
  src: /assets/banner.jpg
  alt: A wide banner showing our new product
  title: Our new product
---
Content goes here.

This HTML attribute defines the path to the structured data key you want to edit and the key name when passing the value to an Editable Region. CloudCannon will pass the value of that key and relabel it with a new key name to your Editable Region so the Visual Editor can re-render that section of your webpage preview.

This HTML attribute is an extension of the behavior of data-prop.

Image Editable Regions must contain an <img> element, either as the element itself or as a child. If the <img> is inside a <picture> element, CloudCannon also updates the src and srcset of any <source> elements when the image changes.

This HTML attribute is required for Image Editable Regions, unless you have defined data-prop.

<html lang="en">
  <body>
    <main>
      <article>
        <div>
            {banner_image &&
              <img
                data-editable="image"
                data-prop-src="banner_image"
                src={banner_image}
              />
            }
        </div>
      </article>
    </main>
  </body>
</html>

---
title: Our new project
author: H. Scott
banner_image: /assets/banner.jpg
date: 2025-08-26T11:17:02+12:00
---
Content goes here.

This HTML attribute passes a literal value to an Editable Region, rather than selecting a value from your data. Use it for values that do not live in any file, such as a fixed label or a display option.

The attribute suffix is the key name CloudCannon passes the value under. CloudCannon lowercases this key name, so data-literal-author-name passes the value under authorname. We recommend single-word key names to avoid confusion.

Values that parse as JSON are passed as structured values. Any other value is passed as a string.

You can also use data-literal on its own to pass a literal value as the entire value of the Editable Region, rather than under a key name.

This HTML attribute is optional for all Editable Regions, and is most useful for Component Editable Regions.

<html lang="en">
  <body>
    <main>
      <article>
        <editable-component
          data-prop="author"
          data-component="author_card"
          data-literal-variant="compact"
        >
          <AuthorCard {...author} variant="compact" />
        </editable-component>
      </article>
    </main>
  </body>
</html>

---
title: Our new project
author:
  name: H. Scott
  role: Support engineer
date: 2025-08-26T11:17:02+12:00
---
Content goes here.

This HTML attribute defines the path to the file you want to edit. CloudCannon will pass the value of that key to your Editable Region so the Visual Editor can re-render that section of your webpage preview.

This HTML attribute is required for Source Editable Regions.

<html lang="en">
  <body>
    <main data-editable="source" data-path="/src/pages/index.astro" data-key="main">
      <img src="/smiling-robot.jpg">
      <h1>Hello!</h1>
    <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
          labore et dolore magna aliqua. Vitae ultricies leo integer malesuada nunc vel risus commodo
          viverra. Adipiscing enim eu turpis egestas pretium.
    </p>
    </main>
  </body>
</html>

This HTML attribute defines which rich text formatting options are available for a Text Editable Region.

Values can be one of the following: span for plain text, text for paragraph-level rich text, or block for multi-paragraph rich text.

By default, data-type is block or text for any Source Editable Regions, data-prop="@content", or Rich Text Inputs, and span where Input type is not Rich Text, or is not configured.

This HTML attribute is optional for Text Editable Regions.

<editable-text data-prop="title" data-type="block">Default text</editable-text>

This HTML attribute toggles whether the Visual Editor will automatically load an Editable Region. When set to true, CloudCannon will only initialize the Editable Region when clicked.

By default, this key is false (i.e., the Visual Editor will not defer loading the Editable Region).

This HTML attribute is optional for Text Editable Regions.

This HTML attribute defines the unique identifier for a Source Editable Region, so CloudCannon can update the correct one if you have several in one file.

This HTML attribute is required for Source Editable Regions.

<html lang="en">
  <body>
    <main>
      <section data-editable="source" data-path="/src/pages/index.astro" data-key="hero">
        <img src="/smiling-robot.jpg">
        <h1>Hello!</h1>
      </section>
      <section data-editable="source" data-path="/src/pages/index.astro" data-key="content">
        <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
          labore et dolore magna aliqua. Vitae ultricies leo integer malesuada nunc vel risus commodo
          viverra. Adipiscing enim eu turpis egestas pretium.
        </p>
      </section>
    </main>
  </body>
</html>

This HTML attribute defines the path to the structured data key where data-id is defined. Must be used in conjunction with data-id on Array Item Editable Regions.

This HTML attribute is optional for simple Array Editable Regions, but required for complex Array Editable Regions (i.e., the array items do not share the same structure).

<html lang="en">
  <body>
    <main>
      <section data-editable="array" data-prop="contentBlocks" data-id-key="_name" data-component-key="_name">
        {
          contentBlocks.map((block) => {
            const Component = components[block._name];
            return <editable-array-item data-id={block._name} data-component={block._name}><Component {...block} /></editable-array-item>;
          })
        }
      </section>
    </main>
  </body>
</html>

This HTML attribute defines the unique ID of an Array Item. The value of data-id should be templating containing the name of the structured data key, which CloudCannon will populate at build time. Must be used in conjunction with data-id-key on Array Editable Regions.

This HTML attribute is optional for simple Array Editable Regions, but required for complex Array Editable Regions (i.e., the array items do not share the same structure).

<html lang="en">
  <body>
    <main>
      <section data-editable="array" data-prop="contentBlocks" data-id-key="_name" data-component-key="_name">
        {
          contentBlocks.map((block) => {
            const Component = components[block._name];
            return <editable-array-item data-id={block._name} data-component={block._name}><Component {...block} /></editable-array-item>;
          })
        }
      </section>
    </main>
  </body>
</html>

This HTML element defines the markup CloudCannon should use when your team adds a new item to an Array Editable Region. Place the <template> element inside your Array Editable Region.

A <template> element with no data-id HTML attribute is the blueprint for every new array item. To use a different blueprint for each type of array item, add the data-id HTML attribute to each <template> element, matching the values of the key named by data-id-key. CloudCannon uses an unkeyed <template> element as the fallback for any array item without a matching blueprint.

If your <template> element contains more than one root element, CloudCannon wraps its contents in an <editable-array-item> web component. CloudCannon adds data-editable="array-item" to the root element of each new array item, so you don't need to include it in your <template> element.

This HTML element is optional. If there is no matching <template> element, CloudCannon renders new array items with the component named by data-component-key or data-component. If there is neither a <template> element nor a component, CloudCannon copies the markup of an existing array item. An empty array with neither a <template> element nor a component will display an error in the Visual Editor.

<ul data-editable="array" data-prop="blocks" data-id-key="type">
  <template data-id="hero">
    <li>
      <h2 data-editable="text" data-prop="title"></h2>
    </li>
  </template>
  <template data-id="quote">
    <li>
      <blockquote data-editable="text" data-prop="quote"></blockquote>
    </li>
  </template>
</ul>

This HTML attribute defines the direction of the Array Editable Region in the Visual Editor. You can match the direction of the array on your webpage by defining this HTML attribute.

CloudCannon uses the direction in three places. When you drag and drop an array item, CloudCannon displays a yellow line on the matching edge of an array item to indicate where it will insert the item. The Context Menu for each array item shows Move up and Move down options for a vertical array, or Move left and Move right options for a horizontal array. CloudCannon also disables the move option that would take the first or last array item past the end of the array.

Values can be one of the following: column for vertical ascending order, row for horizontal ascending order, column-reverse for vertical descending order, and row-reverse for horizontal descending order.

If you do not define data-direction, CloudCannon uses the flex-direction of your Array Editable Region when it has display: flex, and column (i.e., a vertical array with array position one at the top) otherwise. CloudCannon does not detect display: inline-flex or grid layouts, so define data-direction for a horizontal array that uses either. If data-direction has any other value, CloudCannon ignores it and uses the same default behavior.

CloudCannon reads the direction when the Visual Editor loads your Array Editable Region. If your layout changes flex-direction at different screen widths, define data-direction so the direction does not depend on the width of the Visual Editor.

This HTML attribute is optional for Array Editable Regions.

<html lang="en">
  <body>
    <main>
      <section>
        <ul data-editable="array" data-prop="testimonials" data-direction="row">
          {
            testimonials.map((testimonial) => (
              <li data-editable="array-item" >
                <p>{testimonial.quote}</p>
              </li>
            ))
          }
        </ul>
      </section>
    </main>
  </body>
</html>

This HTML attribute defines the path to the structured data key where data-component is defined. Must be used in conjunction with data-component on Array Item Editable Regions.

This HTML attribute is optional for simple Array Editable Regions, but required for complex Array Editable Regions (i.e., the array items do not share the same structure).

<html lang="en">
  <body>
    <main>
      <section data-editable="array" data-prop="contentBlocks" data-id-key="_name" data-component-key="_name">
        {
          contentBlocks.map((block) => {
            const Component = components[block._name];
            return <editable-array-item data-id={block._name} data-component={block._name}><Component {...block} /></editable-array-item>;
          })
        }
      </section>
    </main>
  </body>
</html>

This HTML attribute defines which registered component an Array, Array Item, or Component Editable Region should reference. The value of data-component should be the same name as the component in your registration script.

On an Array Editable Region, data-component acts as a fallback. CloudCannon uses it to render any array item that does not resolve a component from the key named by data-component-key. This is useful when every item in your array uses the same component.

This HTML attribute is optional for simple Array Editable Regions, but required for Component Editable Regions and complex Array Editable Regions (i.e., the array items do not share the same structure).

<editable-component data-prop="cta" data-component="cta">
  <CTA {...Astro.props.cta} />
</editable-component>

import { registerAstroComponent } from '@cloudcannon/editable-regions/astro';
import CTA from '../components/CTA.astro';

// Register your components
registerAstroComponent('cta', CTA);

<html lang="en">
  <body>
    <main>
      <section data-editable="array" data-prop="contentBlocks" data-id-key="_name" data-component-key="_name">
        {
          contentBlocks.map((block) => {
            const Component = components[block._name];
            return <editable-array-item data-id={block._name} data-component={block._name}><Component {...block} /></editable-array-item>;
          })
        }
      </section>
    </main>
  </body>
</html>

This HTML attribute instructs CloudCannon to ignore the data-editable HTML attribute if you do not want Editable Regions.

<html lang="en">
  <body>
    <main>
      <article>
        <h1 data-editable="true" data-cloudcannon-ignore >{title}</h1>
      </article>
    </main>
  </body>
</html>