Configuration reference

Everything you can pass to the editor, how to pass it from every framework, and what each option does. All options on this page are verified against the editor's actual DEFAULTS — if it's documented here, it works.

One package: everything ships as openeditor-text — the loader, the React/Vue/Angular wrappers, and the types. Earlier releases split the wrappers into separate packages; from 2.0 they are subpath imports of this one.

Contents

• Installation
• Passing configuration
  • Plain JavaScript
  • React
  • Next.js
  • Vue 3
  • Angular
• Validation & safety
• Core options
• Sizing
• Content & security
• Toolbar
• Paste
• Images & uploads
• Tables
• Typing behavior
• Insert dialogs & view
• Callbacks & persistence
• Internationalization
• Events
• What changed in 2.0
• Migrating from Jodit

Installation

One package, whatever your framework:

npm i openeditor-text

The React, Vue and Angular wrappers ship inside that package as subpath imports — there is nothing extra to install:

React, Vue and Angular are optional peer dependencies, so you only pull in the one you already use.

Upgrading from 1.x? The separate openeditor-text-react, openeditor-text-vue and openeditor-text-angular packages are no longer used — uninstall them and switch to the subpath imports above. See what changed in 2.0 below.

Passing configuration

Plain JavaScript

Options are the second argument to createEditor:

import { createEditor } from 'openeditor-text';

const editor = await createEditor('#app', {
  endpoint: 'https://your-delivery-host.com',
  theme: 'dark',
  placeholder: 'Write something…',
  maxLength: 5000,
  onChange: ({ html }) => save(html),
});

The first argument is a selector string or an HTMLElement. The toolbar, status bar, and all styling are injected by the editor itself.

Two things are new in 2.x:

• createEditor is asynchronous. Installing this package puts only a small loader on disk; the editor itself is downloaded when your page runs, so creating one returns a promise.
• endpoint is required — it is where the editor is downloaded from. You get the URL when you sign up, or it is your own server if you self-host.

Everything else on this page is an ordinary editor option and behaves exactly as it always has.

React

The wrapper takes the same object via the config prop:

import { OpenEditor } from 'openeditor-text/react';

<OpenEditor
  value={html}
  onChange={(html) => setHtml(html)}
  config={{ placeholder: 'Write something…', maxLength: 5000 }}
/>

Reactive vs construct-time — the wrapper contract (all three frameworks):

// Changing a construct-time option = remount with a key:
<OpenEditor key={locale} config={{ locale }} />

Controlled usage is caret-safe: the wrapper diffs out echoes of its own onChange, so feeding the same HTML back never moves the cursor.

Next.js

The module is safe to import on the server; construction needs a DOM, so render it client-side:

import dynamic from 'next/dynamic';

const OpenEditor = dynamic(
  () => import('openeditor-text/react').then((m) => m.OpenEditor),
  { ssr: false },
);

Then use it exactly as in React above — config file + component is the whole integration.

Vue 3

<script setup>
import { ref } from 'vue';
import { OpenEditor } from 'openeditor-text/vue';

const html = ref('<p>Hello</p>');
const config = { placeholder: 'Write something…', maxLength: 5000 };
</script>

<template>
  <OpenEditor v-model="html" :config="config" />
</template>

A useOpenEditor() composable is also available for bring-your-own-element setups — see the Vue wrapper's types.

Angular

Standalone component + ControlValueAccessor — works with [(ngModel)] and reactive forms:

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { OpenEditorComponent } from 'openeditor-text/angular';

@Component({
  standalone: true,
  imports: [FormsModule, OpenEditorComponent],
  template: `<open-editor [(ngModel)]="html" [config]="config"></open-editor>`,
})
export class AppComponent {
  html = '<p>Hello</p>';
  config = { placeholder: 'Write something…', maxLength: 5000 };
}

FormControl.disable() automatically switches the editor to read-only.

Validation & safety

• Unknown top-level keys are ignored with a console warning, and the warning suggests the closest known key (a misspelling like readOnly → suggests readonly). Nothing throws.
• __proto__ / constructor / prototype keys are dropped — the config merge is prototype-pollution-safe.
• Only the top level is checked; nested shapes (autosave.*, onChange.*) are intentionally open.

Core options

Sizing

// A fixed 500px editor that scrolls internally (Jodit-style fixed height):
await createEditor('#app', { endpoint, height: 500 });

// Grows from 300px, scrolls after 600px:
await createEditor('#app', { endpoint, minHeight: 300, maxHeight: 600 });

Content & security

await createEditor('#app', {
  endpoint,
  defaultContent: '<p>Draft loaded from the server…</p>',
  maxLength: 10000,
  allowTags: ['my-note'],
  allowAttributes: { 'my-note': ['data-kind'] },
});

See SECURITY.md for the full sanitizer model.

Toolbar

toolbar accepts three forms:

toolbar: true                  // default — the full built-in toolbar
toolbar: false                 // no toolbar at all (bring your own UI)
toolbar: { items: [ /* groups */ ] }   // custom layout

Custom layout — toolbar.items

items is an array of groups; each group is an array of item descriptors. Groups render with a separator between them.

An item descriptor is one of:

A minimal writing toolbar:

await createEditor('#app', {
  endpoint,
  toolbar: {
    items: [
      [
        { type: 'button', name: 'bold',   command: 'bold',   icon: 'bold',   labelKey: 'bold' },
        { type: 'button', name: 'italic', command: 'italic', icon: 'italic', labelKey: 'italic' },
      ],
      [
        { type: 'dropdown', name: 'heading', kind: 'heading', labelKey: 'heading' },
      ],
      [
        { type: 'button', name: 'undo', command: 'undo', icon: 'undo', labelKey: 'undo' },
        { type: 'button', name: 'redo', command: 'redo', icon: 'redo', labelKey: 'redo' },
      ],
    ],
  },
});

The default layout (for copy-paste editing)

The built-in toolbar is these groups, in order — recreate it and remove what you don't want:

* styles and textPartLanguage only render when their config option (styles / textPartLanguages) is non-empty.

Plugins (image, link, table, emoji, …) contribute their own toolbar buttons when installed — you don't list those here.

Custom buttons

Custom buttons use the same descriptor as built-ins, with an inline SVG icon and optionally your own registered command:

editor.commands.register('shout', {
  execute: (ed) => ed.commands.execute('insertText', 'HEY!'),
});

// in config:
toolbar: {
  items: [
    [{ type: 'button', name: 'shout', command: 'shout',
       icon: '<svg viewBox="0 0 24 24">…</svg>', tooltip: 'Shout' }],
  ],
}

Paste

// Never prompt; always clean pasted HTML down to canonical tags:
await createEditor('#app', {
  endpoint,
  askBeforePasteHTML: false,
  askBeforePasteFromWord: false,
  defaultActionOnPaste: 'keep',
});

Ctrl/Cmd+Shift+V always pastes as plain text.

Images & uploads

Connecting uploads to your own API + database? This table is the reference; the step-by-step setup guide (with server examples for Node/Express, Next.js, and NestJS, plus auth) lives in Image uploads.

The upload contract

When imageUploadUrl is set, every inserted file (file picker, drag-and-drop, clipboard paste) is sent as:

• Request: POST imageUploadUrl, multipart/form-data, file in the file field.
• Response: JSON with the hosted URL at the top level:

{ "url": "https://cdn.example.com/uploads/photo.webp" }

{ "src": "…" } is accepted as an alias. Optionally include sources to emit a responsive <picture> (the <img> stays as fallback):

{
  "url": "https://cdn.example.com/photo.jpg",
  "sources": [
    { "srcset": "https://cdn.example.com/photo.avif", "type": "image/avif" },
    { "srcset": "https://cdn.example.com/photo-800.jpg 800w", "sizes": "100vw" }
  ]
}

Every returned URL (including each srcset) is scheme-checked with the same URL policy as any src — an unsafe URL rejects the whole upload. The common nested shape { "data": { "url": … } } (NestJS/Laravel-style) is understood out of the box. For any other shape, map it with imageUploadResponse — a function that receives the parsed JSON and returns the URL string (or { url, sources }); this is the equivalent of Jodit's process() hook. Full examples are in the Image uploads guide.

Without imageUploadUrl: local files become data: URIs, which are blocked unless you opt in with imageAllowDataUri: true. Inserting by URL always works.

await createEditor('#app', {
  endpoint,
  imageUploadUrl: 'https://api.example.com/uploads/editor-image',
  imageDefaultWidth: 480,
  imageAvailableClasses: [
    { value: 'img-hero', label: 'Hero' },
    { value: 'img-thumb', label: 'Thumbnail' },
  ],
});

(The image plugin itself — resize handles, alignment, properties dialog, captions — is covered in PLUGINS.md.)

Tables

Typing behavior

Insert dialogs & view

Callbacks & persistence

onChange — one of:

• a function ({ html, text }) => {} — called on every (debounced) change;
• { handler, debounce } — same, with a custom debounce (ms);
• { debounce } — event-only (listen via editor.on('onChange', …)).

The onChange event always fires regardless of this option. In the framework wrappers you use the onChange prop / v-model / ngModel instead — don't double-wire both.

autosave — null (off) or:

autosave: {
  storage: 'localStorage',   // only 'localStorage' is supported
  key: 'oe-draft',           // storage key (default 'oe-draft')
  interval: 30000,           // save interval in ms (default 30000)
  restore: true,             // restore a saved draft on load (default true)
}

Emits autosaveSaved / autosaveRestored / autosaveFailed / autosaveDraftSkipped.

Internationalization (locale)

Open Editor ships a built-in English label set plus four complete locale packs — Spanish, French, German, and Arabic — and a bring-your-own-locale mechanism. Whatever you pass is merged over the English defaults, so partial maps are fine (anything you omit falls back to English).

locale takes a translation map — an object whose keys are label names. Whatever you pass is merged over English, so partial maps are fine:

const editor = await createEditor('#app', {
  endpoint,
  locale: {
    bold: 'Gras',
    italic: 'Italique',
    insertLink: 'Insérer un lien',
    // …only the keys you translate; the rest stay English
  },
});

For a right-to-left language, pair the map with direction:

const editor = await createEditor('#app', {
  endpoint,
  locale: myArabicLabels,
  direction: 'rtl',
});

Or pass a language code to use one of the four shipped packs — Spanish, French, German and Arabic:

const editor = await createEditor('#app', { endpoint, locale: 'es' });

// A region suffix works too, matched by its base language:
await createEditor('#app', { endpoint, locale: navigator.language }); // 'es-MX' → Spanish

Every pack covers the full label set (CI-enforced, so a new UI string can never ship untranslated). An unknown code falls back to English rather than throwing.

Changed in 2.0. In 1.x you imported a pack — import { localeAr } from 'openeditor-text'. That is no longer possible: the engine is downloaded at runtime, so there is nothing on disk to import, and openeditor-text/locales/* does not resolve. Pass the code (or a map) instead — the packs travel with the engine, so no import is needed.

The status bar uses CJK-aware word counting.

Events

Configuration callbacks cover the common cases; everything else is on the frozen event map via editor.on(name, handler) (also once / off):

editor.on('ready', () => console.log('editor is live'));
editor.on('maxLengthExceeded', ({ maxLength }) => toast(`Limit: ${maxLength}`));

* Cancelable — the payload has preventDefault().

In the wrappers, the common ones are props/outputs: React onChange/onReady/onFocus/onBlur/onError; Vue emits change/ready/focus/blur/error; Angular outputs changed/ready/focused/blurred/errored. For anything else, grab the instance (ref / template ref / @ViewChild) and call editor.on(…).

What changed in 2.0

The editor is no longer installed — it is delivered. npm install puts a small loader in node_modules, and the engine is downloaded, integrity-checked and mounted when your page loads. The payoff is that entitlements become live: buy a licence and the features appear on the next page load, with no reinstall, no redeploy and no version bump.

Four things changed for you:

Construction is asynchronous. The engine arrives over the network, so createEditor returns a promise:

// 1.x
const editor = new OpenEditor('#app', { theme: 'dark' });

// 2.x
const editor = await createEditor('#app', {
  endpoint: 'https://your-delivery-host.com',
  theme: 'dark',
});

The wrapper packages are retired. openeditor-text-react, openeditor-text-vue and openeditor-text-angular stopped at 1.2.0 and do not work against a 2.x core — they call the old constructor, which no longer exists as a value. Uninstall them and switch to the subpath imports:

npm uninstall openeditor-text-react   # or -vue / -angular

import { OpenEditor } from 'openeditor-text/react';

Locale packs are selected by code, not imported. locale: 'ar' replaces import { localeAr } — the packs travel with the engine, so there is nothing to import. See Internationalization above.

Everything else — every option, event, command and plugin on this page — is unchanged. Once the editor is constructed, 2.x behaves exactly like 1.x.

Migrating from Jodit

The most-used Jodit options and their equivalents here:

Two habits you can drop: wiring both onBlur and onChange to capture content (here onChange alone is reliable and caret-safe), and saveSelectionOnBlur-style flags (selection save/restore across toolbar clicks is built in).

More: THEMING.md · THEME-TOKENS.md · PLUGINS.md · ACCESSIBILITY.md · SECURITY.md · ERROR-REPORTING.md