Callout

A labelled admonition box — note, tip, warning, or important — with a rich-text body. Use it for asides, gotchas, and warnings inside a page.

This is a custom block — register it via initBridge. The level is the block's variation; the body is a region of child blocks, so it holds real markdown — multiple paragraphs, lists, code.

Developer Reference

Schema

Pass this object inside the blocks option when calling initBridge() to register this block type with the admin UI. See Custom Blocks for the full setup guide.

    callout: {
        id: 'callout',
        title: 'Callout',
        icon: calloutIcon,
        group: 'text',
        // The body is a region of child blocks (a blocks_layout field named
        // `items`), so it holds real markdown — multiple paragraphs, lists, code —
        // authored as blocks, not a single slate value or a data-json blob.
        allowedBlocks: ['slate'],
        variations: [
            { id: 'note', title: 'Note', isDefault: true },
            { id: 'tip', title: 'Tip' },
            { id: 'warning', title: 'Warning' },
            { id: 'important', title: 'Important' },
        ],
        // For an agent (the Inka MCP's describe_block): how to use the block, and
        // examples of it filled in, as stored blocks.
        guidance: 'For an aside, a gotcha or a warning inside a page, set apart from the text around it. '
            + 'The level (its variation) says how much it matters: note for background, tip for a helpful aside, '
            + 'warning for something that can bite, important for a must-know. Keep the body short.',
        examples: [
            {
                title: 'A tip',
                block: {
                    '@type': 'callout', variation: 'tip',
                    blocks: { 'tip-text': { '@type': 'slate', value: [{ type: 'p', children: [{ text: 'Save often: drafts are kept per browser.' }] }], plaintext: 'Save often: drafts are kept per browser.' } },
                    blocks_layout: { items: ['tip-text'] },
                },
            },
            {
                title: 'A warning',
                block: {
                    '@type': 'callout', variation: 'warning',
                    blocks: { 'warning-text': { '@type': 'slate', value: [{ type: 'p', children: [{ text: 'Deleting a section deletes every page inside it.' }] }], plaintext: 'Deleting a section deletes every page inside it.' } },
                    blocks_layout: { items: ['warning-text'] },
                },
            },
        ],
        blockSchema: {
            fieldsets: [{ id: 'default', title: 'Default', fields: ['variation', 'items'] }],
            properties: {
                variation: {
                    title: 'Level',
                    choices: [['note', 'Note'], ['tip', 'Tip'], ['warning', 'Warning'], ['important', 'Important']],
                    default: 'note',
                },
                items: { widget: 'blocks_layout', allowedBlocks: ['slate'] },
            },
            required: [],
        },
    }

JSON Block Data

Example block JSON (as stored in the CMS). This is the data structure your component will receive in the block prop.

{
  "@type": "callout",
  "variation": "note",
  "blocks": {
    "slate-1": {
      "@type": "slate",
      "value": [
        {
          "type": "p",
          "children": [
            {
              "text": "This is a "
            },
            {
              "type": "strong",
              "children": [
                {
                  "text": "note"
                }
              ]
            },
            {
              "text": " — the default level. The body takes normal markdown: "
            },
            {
              "type": "code",
              "children": [
                {
                  "text": "code"
                }
              ]
            },
            {
              "text": ", "
            },
            {
              "type": "link",
              "data": {
                "url": "../frontend-guide/live-preview.md"
              },
              "children": [
                {
                  "text": "links"
                }
              ]
            },
            {
              "text": ", and multiple paragraphs."
            }
          ]
        }
      ],
      "plaintext": "This is a note — the default level. The body takes normal markdown: code, links, and multiple paragraphs."
    }
  },
  "blocks_layout": {
    "items": [
      "slate-1"
    ]
  }
}

Rendering

How this block renders in your frontend. Add its handling to your renderer, or — for list-style blocks — register a fetcher and reuse your list rendering.

const calloutLevels = {
  note:      { label: 'Note',      color: '#2563eb', bg: '#eff6ff' },
  tip:       { label: 'Tip',       color: '#059669', bg: '#ecfdf5' },
  warning:   { label: 'Warning',   color: '#d97706', bg: '#fffbeb' },
  important: { label: 'Important', color: '#dc2626', bg: '#fef2f2' },
};

function CalloutBlock({ block }) {
  const level = calloutLevels[block.variation] || calloutLevels.note;
  const blocks = block.blocks || {};
  const items = block.blocks_layout?.items || [];
  return (
    <aside
      data-block-uid={block['@uid']}
      className={`callout callout--${block.variation || 'note'}`}
      style={{ borderLeft: `4px solid ${level.color}`, background: level.bg, padding: '12px 16px', borderRadius: '4px', margin: '1em 0' }}
    >
      <div className="callout__label" style={{ fontWeight: 700, color: level.color, textTransform: 'uppercase', fontSize: '0.8em', letterSpacing: '0.05em', marginBottom: '4px' }}>
        {level.label}
      </div>
      <div className="callout__body">
        {items.map((id) => (
          <BlockRenderer key={id} block={{ ...blocks[id], '@uid': id }} />
        ))}
      </div>
    </aside>
  );
}