1. Visual editing

Field types in editing mode

When a page is rendered inside the SitecoreAI Page builder canvas, your app must wrap every placeholder, component, and field value in pairs of <code> metadata blocks. The Page builder reads these blocks to build a map of every editable region on the page. These blocks tell the Page builder which parts correspond to which Sitecore items, which fields can be edited inline, and which components can be selected and reordered.

This topic describes the HTML your app must produce for each type of element. It complements Field types in rendering data, which documents the JSON shapes you receive, and Editing architecture, which explains how the Page builder uses the chrome metadata. Use this topic as a reference when building or debugging your editing renderer.

Note

The metadata property and field chromes are only present when sc_editMode: "true" is set in the GraphQL request. In normal rendering, neither the metadata property nor the <code> wrappers should appear in your output.

Metadata in the layout data

When sc_editMode: "true" is set in the GraphQL request, every field object in the layout data includes a metadata property alongside value. This metadata is provided by Sitecore and must not be constructed or modified by your app. When wrapping a field in a chrome, serialize this object verbatim as the text content of the opening <code> block:

"Heading": {
  "value": "Welcome to My Site",
  "metadata": {
    "type": "field render",
    "fieldId": "{FIELD-GUID}",
    "fieldType": "Single-Line Text",
    ...
  }
}

If no metadata property is present on a field object, the field was fetched outside editing mode, or the field is not directly editable. In that case, render the field value without any chrome.

Chrome patterns

There are three types of chrome, each using the same <code> element shape but with a different chrometype attribute value.

Placeholder chrome

Placeholder chrome wraps a placeholder and all the components it contains. The Page builder uses it to identify droppable regions where components can be placed and reordered.

The id attribute of the opening block must be <placeholderKey>_<parentUID>, where parentUID is the uid of the route or the component that owns this placeholder:

<code type="text/sitecore" chrometype="placeholder" class="scpm" kind="open" id="headless-main_<ROUTE_UID>"></code>
<div data-placeholder="headless-main">
    <!-- component chromes and their contents go here -->
</div>
<code type="text/sitecore" chrometype="placeholder" class="scpm" kind="close"></code>

For a top-level placeholder (one that belongs directly to the route), parentUID is the uid of the route item from layout.sitecore.route.uid. For a nested placeholder inside a component (such as a column inside ColumnSplitter), parentUID is the uid of that component.

Rendering chrome

Rendering chrome wraps each individual component. The Page builder uses it to identify components that can be selected, moved, and configured. The id attribute of the opening block is the component's own uid from the layout data:

<code type="text/sitecore" chrometype="rendering" class="scpm" kind="open" id="{COMPONENT-UID}"></code>
<div><!-- component HTML --></div>
<code type="text/sitecore" chrometype="rendering" class="scpm" kind="close"></code>

Field chrome

Field chrome wraps an individual rendered field value. The Page builder uses it to activate a content-editable surface over the field so content authors can click and type. The text content of the opening block is the JSON-serialized metadata object from the field in the layout data:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"type":"field render","fieldId":"{FIELD-GUID}","fieldType":"Single-Line Text",...}</code>
<h1>Welcome to My Site</h1>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

Complete placeholder example

The following example shows all three chrome types together for a placeholder that contains a single component with a single field. This is the smallest complete unit that makes a page region editable in the Page builder.

Layout data:

{
  "sitecore": {
    "route": {
      "uid": "54C8E9B5-0B2C-5363-8FA6-D32A3A302F51",
      "placeholders": {
        "headless-main": [
          {
            "componentName": "Title",
            "uid": "A1B2C3D4-0000-0000-0000-000000000001",
            "fields": {
              "heading": {
                "value": "Welcome to My Site",
                "metadata": {
                  "type": "field render",
                  "fieldId": "{FIELD-GUID}",
                  "fieldType": "Single-Line Text"
                }
              }
            }
          }
        ]
      }
    }
  }
}

Expected HTML output:

<!-- Placeholder open: id = placeholderKey_routeUID -->
<code type="text/sitecore" chrometype="placeholder" class="scpm" kind="open" id="headless-main_54C8E9B5-0B2C-5363-8FA6-D32A3A302F51"></code>
<div data-placeholder="headless-main">

    <!-- Rendering open: id = componentUID -->
    <code type="text/sitecore" chrometype="rendering" class="scpm" kind="open" id="A1B2C3D4-0000-0000-0000-000000000001"></code>

    <!-- Field open: text content is the serialized metadata object -->
    <code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"type":"field render","fieldId":"{FIELD-GUID}","fieldType":"Single-Line Text"}</code>
    <h1>Welcome to My Site</h1>
    <code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

    <code type="text/sitecore" chrometype="rendering" class="scpm" kind="close"></code>

</div>
<code type="text/sitecore" chrometype="placeholder" class="scpm" kind="close"></code>

Field type reference

The following sections show the editing-mode layout data and the HTML output for each built-in field type. In each example, metadata is abbreviated to {...} for readability, but your app must serialize and embed the full object exactly as received.

Single-Line Text and Multi-Line Text

In editing mode, both field types include a metadata property alongside the string value:

"Heading": {
  "value": "Welcome to My Site",
  "metadata": { "fieldType": "Single-Line Text", ... }
}

Both text field types hold a plain string value. Wrap the rendered text in an appropriate element and surround it with field chrome:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"Single-Line Text",...}</code>
<h1>Welcome to My Site</h1>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

If the field value is empty, render an empty field chrome so the Page builder can still activate the inline editing surface:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"Single-Line Text",...}</code>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

Rich Text

In editing mode, the field includes a metadata property alongside the HTML string value:

"Body": {
  "value": "<p>Hello <strong>World</strong></p>",
  "metadata": { "fieldType": "Rich Text", ... }
}

A Rich Text field contains HTML markup. Wrap the raw HTML output (not encoded) in a block element and surround it with field chrome:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"Rich Text",...}</code>
<div><p>Hello <strong>World</strong></p></div>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>
Important

Do not HTML-encode the value before embedding it. The Page builder's editing scripts need valid HTML inside the chrome to activate the inline editor. Encoding the markup produces visible &lt;p&gt; characters instead of an editable paragraph.

If the field value is empty, render an empty field chrome:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"Rich Text",...}</code>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

Number and Integer

In editing mode, both field types include a metadata property alongside the string value:

"Price": {
  "value": "29.99",
  "metadata": { "fieldType": "Number", ... }
}

Number and Integer fields hold a string value in the layout data. Render the string inside an appropriate element and surround it with field chrome:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"Number",...}</code>
<span>29.99</span>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

If the field value is empty, render an empty field chrome:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"Number",...}</code>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

Date and Datetime

In editing mode, both field types include a metadata property alongside the ISO 8601 string value:

"EventDate": {
  "value": "2026-03-11T00:00:00Z",
  "metadata": { "fieldType": "Date", ... }
}

Date and Datetime fields hold an ISO 8601 string. Render the formatted date output and surround it with field chrome:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"Date",...}</code>
<time datetime="2026-03-11T00:00:00Z">March 11, 2026</time>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

If the field value is empty, render an empty field chrome:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"Date",...}</code>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

Image

In editing mode, the field includes a metadata property alongside the value object:

"FeaturedImage": {
  "value": {
    "src":    "/-/media/images/smart-speaker-1.jpg",
    "alt":    "Smart Speaker",
    "width":  "800",
    "height": "600"
  },
  "metadata": { "fieldType": "Image", ... }
}

An Image field value is an object. Render the <img> element and surround it with field chrome. Apply HTML attribute encoding to the src and alt values:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"Image",...}</code>
<img src="/-/media/images/smart-speaker-1.jpg" alt="Smart Speaker" width="800" height="600" />
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

Only src and alt are guaranteed to be present. See Image for the full set of properties the value object can contain.

If value.src is absent or empty, render an empty field chrome so the Page builder can activate an image picker:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"Image",...}</code>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

In editing mode, the field includes a metadata property alongside the value object:

"PromoLink": {
  "value": {
    "href":     "/en/products",
    "text":     "View our products",
    "linktype": "internal",
    "target":   ""
  },
  "metadata": { "fieldType": "General Link", ... }
}

A General Link field value is an object. Render the <a> element and surround it with field chrome:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"General Link",...}</code>
<a href="/en/products">View our products</a>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

The shape of the value object varies based on the linktype property (internal, external, media, or mailto), but the chrome pattern above is the same for all of them. See General Link and General Link with search for the properties of each variant.

If value.href is absent or empty, render an empty field chrome:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"General Link",...}</code>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

File

In editing mode, the field includes a metadata property alongside the value object:

"Attachment": {
  "value": {
    "src":         "/-/media/files/product-spec.pdf",
    "title":       "Product Specification",
    "displayName": "product-spec.pdf"
  },
  "metadata": { "fieldType": "File", ... }
}

A File field value is an object. Render the link to the file and surround it with field chrome:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"File",...}</code>
<a href="/-/media/files/product-spec.pdf">product-spec.pdf</a>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

If value.src is absent or empty, render an empty field chrome:

<code type="text/sitecore" chrometype="field" class="scpm" kind="open">{"fieldType":"File",...}</code>
<code type="text/sitecore" chrometype="field" class="scpm" kind="close"></code>

Nested placeholders

When a component contains its own placeholders (such as ColumnSplitter or Container), those placeholders must also be wrapped in placeholder chrome. The parentUID in the placeholder id must be the uid of the containing component, not the route:

<!-- Rendering open -->
<code type="text/sitecore" chrometype="rendering" class="scpm" kind="open" id="<COMPONENT_UID>"></code>
<div data-component="ColumnSplitter">

    <!-- Nested placeholder: parentUID is the component uid, not the route uid -->
    <code type="text/sitecore" chrometype="placeholder" class="scpm" kind="open" id="<PLACEHOLDER_KEY>_<COMPONENT_UID>"></code>
    <div data-placeholder="<PLACEHOLDER_KEY>">
        <!-- components inside this column -->
    </div>
    <code type="text/sitecore" chrometype="placeholder" class="scpm" kind="close"></code>

</div>
<code type="text/sitecore" chrometype="rendering" class="scpm" kind="close"></code>

If a nested placeholder has the wrong parentUID (for example, if you use the route uid instead of the component uid), the Page builder cannot map component drops in that placeholder to the correct parent item. Components inside the nested placeholder will appear visually but cannot be reordered or configured.

Structural wrapper components

Some components have no editable fields of their own and exist only to expose nested placeholders. Examples include PartialDesignDynamicPlaceholder and full-bleed container wrappers. For these components, there is no field chrome to emit. There is only rendering chrome around the component itself and placeholder chrome around each of its nested placeholders:

<code type="text/sitecore" chrometype="rendering" class="scpm" kind="open" id="<COMPONENT_UID>"></code>

<code type="text/sitecore" chrometype="placeholder" class="scpm" kind="open" id="<PLACEHOLDER_KEY>_<COMPONENT_UID>"></code>
<div data-placeholder="<PLACEHOLDER_KEY>">
    <!-- nested components -->
</div>
<code type="text/sitecore" chrometype="placeholder" class="scpm" kind="close"></code>

<code type="text/sitecore" chrometype="rendering" class="scpm" kind="close"></code>

For more information about how to handle structural wrapper components in your editing renderer, see Add metadata wrappers to the HTML.

If you have suggestions for improving this article, let us know!