Set & get JSON

This guide covers Redactor's block JSON format: loading structured content, exporting it, and the data fields each block type accepts.

For HTML strings (content option, getHtml, insertHtml), see Set & get content.

Document shape#

A Redactor document is a flat array of block objects:

[
    { type: 'heading', data: { level: 1, content: 'Title' } },
    { type: 'text', data: { content: '<p>Body paragraph.</p>' } }
]

Each item has:

Nested structures (layout columns, wrapper children) use a children array inside data. When you export with getJson(), parent blocks include serialized children.

Set JSON on init#

Pass a block array through the data option:

<div id="entry"></div>

const app = Redactor('#entry', {
    data: [
        { type: 'heading', data: { level: 1, content: 'Hello' } },
        { type: 'text', data: { content: 'Loaded from JSON.' } }
    ]
});

data takes priority over host markup. If you also pass content, content wins (see the content guide).

Replace the whole document (API)#

app.setJson([
    { type: 'text', data: { content: 'New document.' } }
]);

Equivalent form:

app.setContent(blocks, { format: 'json', caret: 'end' });

caret works the same as for HTML: false, 'start', or 'end'.

Get JSON#

getJson()

Returns the current document as a block array (cleaned for export).

const blocks = app.getJson();

getContent('json')

Same result through the generic API:

const blocks = app.getContent('json');

getBlocks() and getNodes()

Lower-level access — mounted block instances or root DOM nodes rebuilt from JSON:

const blockInstances = app.getBlocks();
const nodes = app.getNodes();

Use these when you need to work with the editor internals, not for storage.

Output hooks#

Before JSON is returned, Redactor emits output:before:json with { json }. Change json in the handler to post-process export.

Common data fields#

Every block type can include these optional fields in data:

Omitted fields are not written on export.

Nested blocks (children)#

Blocks with children hold other blocks inside them:

On export, getJson() adds children automatically for these parents.

On import, you can either:

1. Put nested blocks in data.children (matches export), or
2. For layout only — use data.columns[].children (see layout).

{
    type: 'wrapper',
    data: {
        wrap: 'section',
        classname: 'callout',
        children: [
            { type: 'text', data: { content: 'Inside the wrapper.' } }
        ]
    }
}

Block types#

text

Paragraph or generic text block (<p> by default).

{ type: 'text', data: { content: 'Plain text or <strong>HTML</strong>.' } }
{ type: 'text', data: { content: 'Locked.', noneditable: true } }
{ type: 'text', data: { content: 'Required slot.', nondeletable: true } }

heading

{ type: 'heading', data: { level: 2, content: 'Section title' } }

address

{ type: 'address', data: { content: '221B Baker Street' } }

image

{
    type: 'image',
    data: {
        src: '/uploads/photo.jpg',
        alt: 'Sample',
        url: 'https://example.com',
        target: '_blank',
        caption: 'Photo caption'
    }
}

list

Bullet or numbered list.

Each item in items:

{
    type: 'list',
    data: {
        numbered: true,
        items: [
            { content: 'First item' },
            { content: 'Second item', items: [{ content: 'Nested item' }] }
        ]
    }
}

todo

Checkbox task list.

Each item:

{
    type: 'todo',
    data: {
        items: [
            { content: 'Ship feature', done: true },
            { content: 'Write docs', done: false }
        ]
    }
}

table

{
    type: 'table',
    data: {
        head: true,
        items: [
            ['Name', 'Role'],
            ['Ada', 'Engineer'],
            ['Grace', 'Scientist']
        ],
        caption: 'Team members'
    }
}

dlist

Definition list (<dl>).

Each item:

{
    type: 'dlist',
    data: {
        items: [
            { term: 'API', desc: 'Application Programming Interface' },
            { term: 'CMS', desc: 'Content Management System' }
        ]
    }
}

quote

{
    type: 'quote',
    data: {
        content: 'The only way to do great work is to love what you do.',
        caption: 'Steve Jobs'
    }
}

pre

Code or preformatted block.

text is accepted as an alias for content on import.

{ type: 'pre', data: { content: 'const x = 1;' } }

details

Collapsible <details> block.

{
    type: 'details',
    data: {
        summary: 'More information',
        content: 'Hidden details text.',
        open: false
    }
}

embed

Video, audio, or iframe embed.

{
    type: 'embed',
    data: {
        type: 'iframe',
        src: 'https://www.youtube.com/embed/…',
        width: '560',
        height: '315',
        responsive: true
    }
}

layout

Multi-column grid.

Each entry in columns:

{
    type: 'layout',
    data: {
        pattern: '50%|50%',
        columns: [
            { width: '50%', children: [{ type: 'text', data: { content: 'Left' } }] },
            { width: '50%', children: [{ type: 'text', data: { content: 'Right' } }] }
        ]
    }
}

column

A single column — usually nested inside layout via children. Rarely used as a top-level block.

wrapper

Groups blocks in a custom wrapper element.

{
    type: 'wrapper',
    data: {
        wrap: 'aside',
        classname: 'sidebar',
        children: [
            { type: 'text', data: { content: 'Sidebar note.' } }
        ]
    }
}

noneditable

Fixed HTML the user cannot edit in the UI.

{ type: 'noneditable', data: { content: '<span>Locked badge</span>' } }

mergetag

Inline merge field / variable token.

{ type: 'mergetag', data: { content: '' } }

Usually appears inside text or heading content HTML rather than as a separate top-level block.

line

Horizontal rule (<hr>). No type-specific fields — common data only.

{ type: 'line' }