Definition and props

The contract

{ "type": "circle-gallery", "title": "Circle Gallery", "version": "1.0.0", "icon": "mdi:rotate-3d-variant", "category": "Gallery", "description": "Images orbiting a centre point.", "root": { "tag": "section", "class": "cc-circle-gallery" }, "libraries": [], "capabilities": [], "props": [ { "id": "images", "type": "media-list", "label": "Images", "group": "Content" }, { "id": "radius", "type": "number", "label": "Orbit radius", "group": "Layout", "min": 60, "max": 600, "step": 10, "unit": "px", "default": 220 }, { "id": "speed", "type": "slider", "label": "Seconds per turn", "group": "Motion", "min": 4, "max": 90, "step": 1, "unit": "s", "default": 24 }, { "id": "accent", "type": "color", "label": "Accent", "default": "var(--sb-accent, #6366f1)" }, { "id": "pauseOnHover", "type": "toggle", "label": "Pause on hover", "default": true } ], "defaultStyle": { "base": { "paddingTop": "64px", "paddingBottom": "64px" } }, "presets": [ { "title": "Slow drift", "props": { "speed": 45, "radius": 260 } } ], "example": { "props": { "speed": 20 } }, "fallback": "<h2>Our work</h2><p>A rotating gallery of recent projects.</p>" }

type: the block's identifier. Your organization's scope may be added to it on save; use the saved type everywhere, including inregister().

root.tag: one ofdiv,section,article,aside,nav,figure.

styleTemplate(optional): which style controls the block gets. Defaultsection-base; alsosection-full,card-base,atom-text,atom-media,layout-base,nav-item,widget-base,minimal.

defaultStyle: style applied when the block is dropped. Put a starting background here, never on the root in your CSS, so people can change it.

presets: named starter settings people can pick.example: props used to preview it unconfigured.

fallback: plain HTML for search engines and first paint (seeSEO). Scripts, styles, iframes, inline handlers andjavascript:links are rejected.

librariesandcapabilities: seeApproved librariesandData access.

Prop types

text,textarea,rich-text,color,icon,link,date,select(needsoptions),binding: arrive as a string. A binding prop opens the site's data-binding picker and arrives resolved.

number,slider: a number (as a string in plain JS).min,max,stepandunitgive it a scrubber.

toggle:"true"or"false".

media: a resolved URL. On published pages library pictures arrive as an optimised, resized variant (1600 px wide by default; setimageWidthfrom 320 to 2560, or 0 for the original).

media-list: a JSON array of URLs.

list(needsitemFields),chips: a JSON array.

Every prop reaches plain JavaScript as a data-* attribute on the root, named from the id: images becomes data-images, pauseOnHover becomes data-pause-on-hover. React components get typed props instead.

Never put a secret or private API key in a prop: props are visible in the published HTML.

Editable text on the canvas

Mark the element that shows a text prop with data-sb-prop="<id>" so people can double-click it on the canvas and edit it in place. A component that draws text on a canvas or in SVG defines regions(el, props, t) instead, returning [{prop, x, y, width, height, style}].