Dollie Editor SDK
Playground

Dollie Editor SDK guide

Fields, Slots, and Elements

Learn how typed fields make component props editable and how slots accept reusable visuals

Fields describe the part of a component an Editor user or Copilot may change.

They do not describe every implementation detail. Spacing algorithms, animation timing, internal state, and layout mechanics normally remain inside the React component.

Fields map to props

A text prop becomes a text Field. A boolean becomes a switch. A string-literal union becomes a select. Arrays and objects create structured nested controls.

type CourseHeroProps = {
    headline?: string;
    description?: string;
    alignment?: 'left' | 'center';
    showInstructor?: boolean;
};

The corresponding Fields drive:

  • the props inspector;
  • validation for Element values;
  • the field descriptions available to a Copilot.

The dollie-editor fields command can derive Fields from TypeScript props and JSDoc.

Slots reserve visual space

A Field of kind element is a Slot.

The Section controls where the Slot appears and which Element kinds it accepts:

{
    kind: 'element',
    key: 'media',
    label: 'Hero visual',
    optional: true,
    accepts: ['illustration', 'image'],
}

An Editor user can swap the visual without changing the hero layout.

Element kinds

Dollie Editor supports three Element kinds.

Illustration

A registered React visual, such as a product mockup, chart, process diagram, or ambient graphic.

"free-orbit-rings"

A bare string is the permanent shorthand for an Illustration id.

Illustrations may optionally carry portable wrapper layout controls:

{
  "kind": "illustration",
  "id": "free-orbit-rings",
  "layout": {
    "padding": 24,
    "offsetX": -12,
    "offsetY": 8,
    "className": "md:p-8"
  }
}

padding accepts 0–96 pixels, while offsetX and offsetY accept -200–200 pixels. The Editor renders adjusted Illustrations inside an SDK-owned wrapper; refs without layout keep the existing component DOM. className is applied to that wrapper as an escape hatch, but utility classes only take effect when the host stylesheet compiled them. The numeric controls always render as inline styles.

Image

An inline asset reference supplied by the host or user:

{
  "kind": "image",
  "src": "/images/course-cover.jpg",
  "alt": "Course workbook and laptop",
  "fit": "cover",
  "effects": {
    "opacity": 75,
    "brightness": 90,
    "saturation": 0
  }
}

Images are not registered in the Catalog. Optional effects use widely supported CSS image controls: opacity (0–100), brightness (0–200), contrast (0–200), saturation (0–200), grayscale (0–100), and blur (0–20 pixels). Omitted controls preserve the source image.

Widget

A registered dynamic component, often backed by host data:

{
  "kind": "widget",
  "id": "academy-next-session",
  "props": {
    "title": "Next live session"
  }
}

Widgets can expose Fields of their own.

What belongs in a Slot

Use a Slot when a user might replace a visual with a different compatible visual.

Good candidates:

  • a hero mockup;
  • a chart;
  • an illustration;
  • a product screenshot;
  • a dynamic recent-activity Widget.

Keep structural texture inside the Section:

  • a small decorative sparkle;
  • background gradients;
  • layout grids;
  • animation choreography.

Keep content images as data when they remain the same kind of content:

  • avatars;
  • instructor portraits;
  • customer logos.

Validation protects the boundary

Validation reports:

  • invalid_element for malformed references;
  • element_kind_not_allowed when a Slot rejects the kind;
  • unknown_element for an unregistered Illustration or Widget id.

The Section still owns a designed fallback for an empty optional Slot.