---
title: "Editor.js → Blok Full Migration Reference"
description: "The complete reference: renamed APIs, plugin equivalents, CSS variable mappings, and verification steps."
source: https://blokeditor.com/migration/reference/
lastmod: 2026-07-11
---

# Migration reference

Every rename the codemod performs, the CSS map, and tool-by-tool compatibility.

## Run the codemod

Preview first, then apply.

1 Preview Preview what will change

```
npx -p @bloklabs/core migrate-from-editorjs ./src --dry-run
```

2 Apply Apply the changes to your files

```
npx -p @bloklabs/core migrate-from-editorjs ./src
```

### Options

--dry-run Preview changes without modifying files

--verbose Show detailed output for each file processed

--use-library-i18n Use Blok's built-in translations (69 locales)

## What changes

Every rename the codemod performs, before and after.

### Imports

− `import EditorJS from '@editorjs/editorjs';`

+ `import { Blok } from '@bloklabs/core';`

### Tool imports

− `import Header from '@editorjs/header';`

+ `import { Header } from '@bloklabs/core/tools';`

### Types

− `import type { EditorConfig } from '@editorjs/editorjs';`

+ `import type { BlokConfig } from '@editorjs/editorjs'; // specifier still needs a manual change`

### CSS selectors

− `.ce-block`

+ `[data-blok-element]`

### Default holder

− `<div id="editorjs"></div>`

+ `<div id="blok"></div>`

### Data attributes

− `data-id`

+ `data-blok-id`

## Update your CSS

Blok replaces Editor.js class names with data attributes. Map any custom styles with this reference.

From EditorJS Blok

`.codex-editor` `[data-blok-editor]`

`.ce-block` `[data-blok-element]`

`.ce-block--selected` `[data-blok-selected="true"]`

`.ce-toolbar` `[data-blok-toolbar]`

`.ce-inline-toolbar` `[data-blok-testid="inline-toolbar"]`

`.ce-toolbar__settings-btn` `[data-blok-settings-toggler]`

`.ce-popover` `[data-blok-popover]`

`data-placeholder` `data-blok-placeholder`

## Migrate custom tools

Block tools port unchanged. Inline tools return a MenuConfig — or wrap the old class and skip the rewrite.

### Inline tool render() → MenuConfig

− `render() { /* returns an HTMLElement button */ }`

+ `render() { return { icon, name, onActivate, isActive }; }`

### Fast path — wrapLegacyInlineTool

Wrap an existing EditorJS inline tool class instead of rewriting it. The shim maps the legacy API onto MenuConfig and keeps the tool's title, shortcut, sanitize config and icon. Without it, Blok skips a legacy HTMLElement render() and the tool silently vanishes.

marker: wrapLegacyInlineTool(MarkerTool)

### Block tools port unchanged

Blok reads the same keys — render, save, validate, renderSettings, merge, onPaste, and the toolbox/conversionConfig statics. Optionally add setReadOnly(state) for cheaper read-only toggling.

### Dropped fields & migration warnings

When Blok loads legacy data at runtime it logs a one-time console.warn per block and field naming what was dropped, and migrateLegacyBlocks from @bloklabs/core/migrate does the same — passing onLossyField replaces that console warning with your own callback. migrate() always installs one, so it stays silent and hands you the drops in report.lossyFields instead. The codemod is the exception: it hard-wires an empty warn sink and migrates silently, so check this table before running it if you depend on any of these fields.

Block Dropped field(s)

`quote` alignment (caption is auto-migrated into a following paragraph)

`image` withBackground

`linkTool` meta.site_name

`list item` meta.counterType (meta.checked and meta.start are migrated)

`attaches` file.name, file.size, file.extension (the file metadata is dropped when the block becomes a bookmark)

`marker` the highlight itself (Editor.js writes <mark class="cdx-marker"> with no inline color; Blok's marker sanitizer allows no attributes on such a mark and preflight resets the UA highlight, so the text survives unhighlighted)

## Verify your content

Compatibility depends on the tools your content uses, not on your Editor.js version.

### Drop-in unchanged

These tools load your saved data as-is.

- `paragraph`
- `header`
- `code`
- `embed`
- `inlineCode`
- `audio`

### Auto-migrated

Converted by the shared legacy grammar — the same rules run at runtime and in the codemod.

- `list`
- `checklist`
- `toggleList`
- `callout`
- `image`
- `simple-image`
- `linkTool`
- `delimiter`
- `quote`
- `table`
- `raw`
- `warning`
- `attaches`

### Not bundled

Blok ships no equivalent — register your own tool or keep the Editor.js one.

- `personality`
- `button`

Unknown block types render as stubs and log a "Tool «name» is not found" warning. Their data is preserved — register the tool later and the block comes back.