Visual component forms

Define the properties and editable slots writers see when they insert a custom component.

Use studio.components.json beside package.json when a writer should be able to insert a website component and edit its properties in a form. The website supplies the actual renderer. Without a registry, custom component markup remains editable in source.

{
  "version": 1,
  "components": [{
    "name": "callout",
    "syntax": "markdoc",
    "label": "Callout",
    "props": {
      "type": "object",
      "properties": {
        "tone": { "type": "string", "enum": ["note", "warning"], "default": "note" }
      }
    },
    "slots": {
      "default": { "label": "Message", "format": "markdown" }
    }
  }]
}
KeyValues and effect
versionRequired. Use the number 1.
componentsRequired array, up to 100 definitions. The file limit is 256 KiB.
name and syntaxRequired on each definition. The pair must be unique. Names start with a lowercase letter and can contain lowercase letters, digits, and hyphens. Use markdoc for Markdoc tags or mdc for MDC containers. Markdoc reserves if, else, slot, and partial.
label, description, iconA nonempty label names the component in the editor. Optional strings supply a description and icon.
componentOptional string identifying the implementation file for developers. The website registers and renders the implementation.
propsRequired JSON Schema with type: "object" and a properties object. Use properties: {} for a component without options. Each property must be a string, boolean, number, or integer. Start its name with a letter and use letters, digits, underscores, or hyphens thereafter.
props.propertiesEach property can have a title, description, enum, default, and validation constraints appropriate to its type. List mandatory property names in props.required. Use props.additionalProperties to control extra properties.
slotsOptional map of editable content areas. Markdoc supports default. MDC also supports named slots. Slot names follow the same lowercase naming rule as component names.
slots.<name>.formatRequired for each slot. Use markdown.
slots.<name>.label, default, requiredOptional display label, starting Markdown string, and boolean required flag. With these omitted, the slot has no preset content or required flag.