Inline Editing

data-caret is the wedge. 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" }
  }
}

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

There’s no client-side hydration of CMS content. A response-rewriting middleware reads stored entries and replaces template defaults at render time, before HTML hits the browser.

Visitor	What they see
Public visitor	Stored content (or template defaults if no edit exists)
Editor (with session cookie)	Same content, plus inline editor JS that turns clicks into edits
Visitor with JS disabled	Latest stored content — rewriting happened server-side

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.

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

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.