Inline Editing

data-caret is the one attribute that makes an element editable. This page covers every shape it takes.

The binding triple

Every editable field resolves to three things:

collection :: id :: field

Part	Description	Example
collection	Group of entries	pages, site, products
id	Entry within the collection	home, global, widget-x
field	Property name on the entry data	headline, hero.title

You can write all three on a single element, or split them across a parent scope and child fields.

Three ways to write a binding

Fully qualified

<h1 data-caret="pages::home::headline">Welcome</h1>

Use this for one-off bindings that don’t share a parent.

With a scope (recommended)

<main data-caret-scope="pages::home">
  <h1 data-caret="headline">Welcome</h1>
  <p data-caret="intro">Tagline...</p>
</main>

data-caret-scope="collection::id" on a parent shortens every child to just the field name. Cleanest pattern for pages.

Nested objects

<section data-caret-scope="site::global">
  <h2 data-caret="company.name">Acme Inc.</h2>
  <p data-caret="company.tagline">Quality since 1923</p>
</section>

Dot-paths in the field portion (company.name) resolve to nested objects in the stored JSON.

The nested-object form maps to:

{
  "id": "global",
  "data": {
    "company": { "name": "Acme Inc.", "tagline": "Quality since 1923" }
  }
}

Binding in a loop with bindEntry

When you render a list and can’t hand-write a data-caret string per item, use the bindEntry helper. It takes a { collection, id } and returns a function that produces the attributes for any field — spread the result onto the element.

---
import { bindEntry } from '@caretcms/core';
import { getLiveCollection } from 'astro:content';

const { entries } = await getLiveCollection('gallery');
---

<ul>
  {entries.map((item) => {
    const bind = bindEntry({ collection: 'gallery', id: item.id });
    return (
      <li>
        <img {...bind('src')} src={item.data.src} alt={item.data.alt} />
        <figcaption {...bind('caption')}>{item.data.caption}</figcaption>
      </li>
    );
  })}
</ul>

bind('caption') expands to data-caret="gallery::<id>::caption". Pass { rich: true } (bind('body', { rich: true })) to add data-caret-rich and allow formatted text instead of plain text.

Rich text (data-caret-rich)

For headings or paragraphs with inline formatting (<strong>, <em>, links, …), use data-caret-rich:

<p data-caret="body" data-caret-rich>
  Ship <strong>faster</strong> with CaretCMS.
</p>

The editor shows a floating format toolbar on text selection. Only sanitizer-safe inline tags round-trip. To keep CSS classes on spans, add them to allowedClasses:

caret({ allowedClasses: { span: ['gold'] } })

Caretize --rich-class can tag styled blocks and print the exact allowedClasses snippet you need.

Editable element types

Text

Any text-bearing element (h1–h6, p, span, div, li, a, button) becomes contenteditable when an editor session is active.

<h1 data-caret="headline">Click me</h1>

Pressing Enter saves. Clicking outside saves. Escape cancels and reverts. The save uses optimistic locking — if someone else saved between your read and write, the request fails with 409 Conflict and you see a toast.

Images

<img data-caret="..."> opens an upload dialog on click and swaps src after the upload.

<img
  data-caret="hero.image"
  src="/img/hero.jpg"
  alt="Hero"
  width="1200"
  height="630"
/>

The default localUploads provider writes files to public/uploads/<hash>.<ext> and stores the resulting URL in the field. With Cloudflare R2, files go to your bucket and the public URL is recorded.

Editors can update alt text by clicking the image and editing the alt field in the upload dialog.

Section composer

Wrap a list of repeating sections with data-caret-section-composer and each section becomes reorderable, toggleable, and removable from the editor:

<div data-caret-scope="pages::home" data-caret-section-composer="sections">
  <section data-caret-section="hero">…</section>
  <section data-caret-section="features">…</section>
  <section data-caret-section="cta">…</section>
</div>

Stored as an ordered array of section names with per-section enabled flags.

What renders, and when

Server delivery

Response-rewriting middleware reads stored entries and replaces template defaults at render time, before HTML hits the browser.

Static delivery

At astro build, CaretCMS bakes stored content into generated HTML. Production has no middleware — rebuild after publish. See Static delivery.

Visitor	What they see
Public visitor	Published content (or template defaults if no edit exists)
Editor (with session cookie)	Draft overlay when preview is on; otherwise published + inline editor
Visitor with JS disabled	Latest published content (server: rewritten at request time; static: baked at build)

Disabling the editor on specific subtrees

<footer data-caret-disable>
  <p>© 2026 — not editable</p>
</footer>

To disable globally, set enableInlineEditor: false in caret(). The admin UI and API still work; only the click-to-edit hydration is skipped.

How the editor loads

Zero work for public visitors

The integration injects a tiny bootstrap script on every page. It checks for data-caret elements and an authenticated session before loading the heavier editor JS. Public visitors never download editor assets.

Order of operations:

1. Bootstrap checks for any data-caret element. If none, exits.
2. Calls GET /api/cms/auth/session to check for a logged-in editor.
3. If authenticated, injects editor.css and editor.js from /__caret/.

Editor assets are versioned with ?v=<timestamp> to bust cache after redeploys.

Signed in, but nothing to edit?

If you’re logged in and land on a live page that has no data-caret bindings yet, CaretCMS shows a small “Signed in · no editable fields on this page” hint pointing you at the next step — so an un-annotated page reads as “nothing to edit here” instead of looking broken. The hint is editor-only (anonymous visitors never see it), comes from the server with no extra client request, and never appears inside the Studio or on API/asset routes.

Field paths and security

Field paths support dot-notation (hero.title, meta.og.image) but reject prototype-pollution attempts:

Rejected by the mutation engine

'__proto__.x'
'constructor.prototype.y'
'a.__proto__.b'

The mutation engine returns 400 Bad Request for these. There’s a regression test for it (tests/unit/mutations-locking.test.ts).

Image alt text

Editors can update alt text from the upload dialog. Stored as a sibling field — by convention <field>.alt:

---
import { getLiveEntry } from 'astro:content';
const { entry: home } = await getLiveEntry('pages', 'home');
---

<img
  data-caret="hero.image"
  src={home?.data.hero?.image ?? '/img/hero.jpg'}
  alt={home?.data.hero?.alt ?? 'Hero'}
/>

Next steps

Caretize CLI Auto-tag templates from existing markup.

Schemas Give your fields proper labels and validation.

Content Studio Structured editing instead of click-to-edit.

Live Collections Read the same data from astro:content.