Configuration

This page contains guide for Editor.js tunings.

☝️

Tip

The most actual list of available configuration properties — see here.

Passing saved data

To initialize the Editor with previously saved data, pass it through the data property:

const editor = new EditorJS({ /** * Id of Element that should contain the Editor */ holderId : 'editorjs', /** * Available Tools list. * Pass Tool's class or Settings object for each Tool you want to use */ tools: { header: { class: Header, inlineToolbar : true }, // ... }, /** * Previously saved data that should be rendered */ data: {} });

Format of the data object should be the same as returned by Editor saving.

Editor ready callback

Editor.js needs a bit time to initialize. It is an asynchronous action so it won't block execution of your main script.

If you need to know when editor instance is ready you can use one of the following ways:

Pass onReady property to the configuration object

It must be a function:

var editor = new EditorJS({ // Other configuration properties /** * onReady callback */ onReady: () => { console.log('Editor.js is ready to work!') } });

Use isReady promise

After you create a new EditorJS object, it will contain isReady property. It is a Promise object that will be resolved when the Editor is ready for work and rejected otherwise. If there is an error during initialization the isReady promise will be rejected with an error message.

var editor = new EditorJS(); editor.isReady .then(() => { console.log('Editor.js is ready to work!') /** Do anything you need after editor initialization */ }) .catch((reason) => { console.log(`Editor.js initialization failed because of ${reason}`) });

You can use async/await to keep your code looking more clear:

var editor = new EditorJS(); try { await editor.isReady; console.log('Editor.js is ready to work!') /** Do anything you need after editor initialization */ } catch (reason) { console.log(`Editor.js initialization failed because of ${reason}`) }

Editor modifications callback

Similar to onReady callback, you can use the onChange callback to handle any modifications inside the Editor:

var editor = new EditorJS({ // Other configuration properties /** * onReady callback */ onReady: () => {console.log('Editor.js is ready to work!')}, /** * onChange callback */ onChange: (api, event) => { console.log('Now I know that Editor\'s content changed!', event) } });

The editor's onChange callback accepts CustomEvent describing what happened with the Block. (Available since 2.23.0)

This CustomEvent has:

`type`	string	Mutation type (`Added`, `Removed`, `Moved`, `Changed`)
`details.target`	BlockAPI	changed Block API
`details.*`	any	Additional data

Change the default Block

By default, Editor.js contains Paragraph Block included in a bundle. This Block is called «default»: it will be appended after Enter key pressing and with an empty Editor. Also, it accepts paste patterns that allow rendering other Blocks by pasted URLs.

There is the ability to change the default Block for your own. Use the defaultBlock option for this:

import MyParagraph from 'my-paragraph.js'; const editor = new EditorJS({ /** * Available Tools list. */ tools: { myOwnParagraph: MyParagraph }, /** * This Tool will be used as default */ defaultBlock: 'myOwnParagraph' })

The name of the default Block should be equal to one of Tool`s keys passed by tools option.

Autofocus

Pass autofocus option if you want to set a Caret to the Editor after initialization:

const editor = new EditorJS({ // other configuration options /** * Enable autofocus */ autofocus: true })

Placeholder

Pass the placeholder option if you want to set a custom placeholder:

const editor = new EditorJS({ ... placeholder: 'Let`s write an awesome story!' ... });

☝️

Note.

If you are using custom Initial Block, `placeholder` property is passed in `config` object to your Tool constructor

Log level

The editor outputs some information to the console. You can configure how much information you want to see. You can provide log level via logLevel property:

const editor = new EditorJS({ ... logLevel: 'ERROR' ... });

Here is available levels:

Value	Description
`VERBOSE`	Show all messages (default)
`INFO`	Show info and debug messages
`WARN`	Show only warn messages
`ERROR`	Show only error messages

Internationalization

Editor.js provides an API for Internationalization that allows localizing all UI texts of the editor's core and plugins.

To create localization of the editor.js you need to provide the i18n option with the messages dictionary. The messages object should contain the ui, toolNames, tools and the blockTunes sections.

const editor = new EditorJS({ ... i18n: { messages: { ui: { // Translations of internal UI components of the editor.js core }, toolNames: { // Section for translation Tool Names: both block and inline tools }, tools: { // Section for passing translations to the external tools classes // The first-level keys of this object should be equal of keys ot the 'tools' property of EditorConfig }, blockTunes: { // Section allows to translate Block Tunes }, } } ... });

See detailed description of the i18n config here: https://editorjs.io/internationalization

Read-Only mode

Since the 2.19.0 version, Editor.js can be initialized in the read-only mode. That means that users won't have the ability to change the document content.

To initialize this mode, pass the readOnly: true option via Editor Config:

const editor = new EditorJS({ // ... readOnly: true, // ... });

You can also toggle the read-only mode on the fly using an API method:

const editor = new EditorJS(); editor.readOnly.toggle();

☝️

Important

Each of the Block Tools you use MUST support the read-only mode to enable this mode in the editor.

You can specify the common order of Inline tools using the inlineToolbar property.

The common inlineToolbar property can be overridden by the tool's inlineToolbar property.

const editor = new EditorJS({ // ... /** * Common Inline Toolbar settings * - if true (or not specified), the order from 'tool' property will be used (default) * - if an array of tool names, this order will be used */ inlineToolbar: ['link', 'marker', 'bold', 'italic'], // inlineToolbar: true, /** * Tools list */ tools: { header: { class: Header, /** * This property will override the common settings * That means that this tool will have only Marker and Link inline tools * If 'true', the common settings will be used. * If 'false' or omitted, the Inline Toolbar wont be shown */ inlineToolbar: ['marker', 'link'], config: { placeholder: 'Header' }, shortcut: 'CMD+SHIFT+H' }, } });

Block Tunes connection

If you have connected any Block Tunes, you need to specify them in tunes property

const editor = new EditorJS({ tools: { myTune: MyTune }, tunes: ['myTune'] });

If you want to enable Tune for particular Tool you can specify it in Tool configuration:

const editor = new EditorJS({ tools: { myTune: MyTune, blockTool: { class: MyBlockTool, tunes: ['myTune'] } } });