Migration from 4.x

This guide helps you move an existing Redactor 4 integration to Redactor 5. It focuses on settings, the public API, and events — the surfaces most integrations and plugins use.

Redactor 5 keeps the same entry point (Redactor('#entry', options) → app), but several option names, method paths, and event names changed. Prefer the 5.x names in new code; where noted, older forms still work as aliases.

Related references:

• Settings
• API
• Events
• Create a plugin
• Set & get JSON

What changed at a glance#

Settings#

Update constructor options first. Most options keep the same meaning; several were renamed, nested, or replaced.

Renamed or reshaped

// Redactor 4
Redactor('#entry', {
    clicktoedit: true,
    sync: false,
    syncDelay: 100,
    state: { limit: 100 },
    addPosition: 'bottom',
    popups: {
        format: ['text', 'h1', 'h2', 'h3']
    }
});

// Redactor 5
Redactor('#entry', {
    clickToEdit: true,
    sync: { enabled: false, debounce: 100 },
    history: { limit: 100 },
    contentInsert: 'end',
    dropdown: {
        format: ['text', 'h1', 'h2', 'h3']
    }
});

Removed from settings docs (verify in your build)

These were documented in 4.x and no longer have a dedicated settings page in 5.x. Do not assume runtime parity — replace or drop them deliberately:

classes, reorder, structure, grammarly, scrollOverflow, block.outline, paragraphizer, global drop (use image.drop), image.states, embed.script.

New options worth knowing

Plugins accept a string array as before, or a map with per-plugin options:

Redactor('#entry', {
    plugins: {
        counter: { plugin: CounterPlugin, options: { /* … */ } }
    }
});

See Plugins settings and AI settings.

Public API#

Calling patterns

Modules such as toolbar, block, and addbar still hang off app (app.toolbar.add(…)). You can also use app.getModule('toolbar') or app.invoke('toolbar.add', …).

Content and editor methods

// Redactor 4
app.editor.setContent({ html: '<p>Hello</p>' });
const html = app.editor.getContent();
app.editor.insertContent({ html: '<p>More</p>' });
app.editor.setFocus('end');

// Redactor 5
app.setContent('<p>Hello</p>');
const html = app.getHtml();
app.insertHtml('<p>More</p>', { caret: 'end' });
app.focusEditor({ position: 'end' });

Modules and services

Block focus APIs moved toward explicit focus methods:

// Redactor 4 (typical)
app.block.set(el, 'end');
app.block.unset();

// Redactor 5
app.block.focus(el, { caret: 'end' });
app.block.clearFocus();

The Dom wrapper (app.$doc, jQuery-like chain) is no longer part of the public API docs — work with native elements and services.

Full module and service lists: API overview.

Events#

Notation and config

Docs use colons: editor:ready. The legacy dotted form (editor.ready) is equivalent when the segments are the same — editor.ready ↔ editor:ready.

That is only a notation alias. It does not rename events that changed identity. For example, editor.load is not the same as editor:ready.

// Redactor 4
Redactor('#entry', {
    subscribe: {
        'editor.load': function() {
            // …
        },
        'editor.keydown': function(event) {
            // …
        }
    }
});

// Redactor 5
Redactor('#entry', {
    events: {
        'editor:ready'() {
            // …
        },
        'key:down'({ event }) {
            // …
        }
    }
});

You can also subscribe after init with app.on / app.off — see Events overview.

Same name, new punctuation

These keep the same segments — switch dots to colons (or keep the dotted form as notation).

Renamed events (update handlers)

For “document changed” listeners, prefer blocks:change in new code (you can still listen to editor:change).

Parse / output pipeline

HTML parse and unparse hooks were split into cleaner, parser, and output events. Map carefully and re-test:

Events without a direct replacement

No dedicated 5.x counterpart is documented for these 4.x events:

• editor.mouseover
• block.duplicate
• list.item
• embed.change
• source.before.open
• source.before.close
• source.change
• app.before.stop
• link.click
• image.click

For click-related cases, use the generic click event or focus events and filter by target or block type.

Plugins#

Rewrite object-literal plugins as classes with constructor(app, options), start(), and optional load() / stop().

// Redactor 4 (concept)
Redactor.add('plugin', 'hello', {
    start() {
        this.app.toolbar.add('hello', { title: 'Hi', command: 'hello.run' });
    },
    run() { /* … */ }
});

// Redactor 5
class HelloPlugin {
    constructor(app, options = {}) {
        this.app = app;
        this.options = options;
    }

    start() {
        this.app.toolbar.add('hello', {
            title: 'Hi',
            command: 'hello.run'
        });
    }

    run() {
        this.app.insertHtml('<p>Hello</p>', { caret: 'end' });
    }
}

Redactor('#entry', {
    plugins: ['hello'],
    // or: plugins: { hello: { plugin: HelloPlugin } }
});

Inside plugins, replace this.opts / this.lang / this.app.create(…) / broadcast with the 5.x patterns above. Full walkthrough: Create a plugin.

Suggested migration steps#

1. Swap the Redactor 5 package (CSS/JS) and open the page — fix init errors first.
2. Update settings renames (clickToEdit, dropdown, sync, history, …).
3. Replace app.editor.* and app.state.* call sites.
4. Replace app.create(…) with getService / app.utils.
5. Move subscribe → events, update renamed event names (especially editor.load, keys, clipboard, DnD, block focus).
6. Port custom plugins to classes; re-test toolbar commands and services.
7. Re-check paste/clean/output hooks if you transform HTML on the way in or out.
8. Optionally adopt new surfaces: Host tabs, JSON content, Premium features.

If something still fails after these steps, compare the old call with the matching page under Settings, API, or Events — method and payload shapes may have changed even when the feature still exists.