---
title: "Blok Class API — new Blok(), isReady, destroy"
description: "Create, await, and tear down an editor instance, and what is safe to call before isReady resolves."
source: https://blokeditor.com/docs/core/
lastmod: 2026-10-07
---

Framework JavaScript

Core Blok Class

On this page save()

# The Blok class: create and destroy an editor

The main editor class. It creates the Blok editor instance and manages it. Every namespace a tool reaches through `api.*` is also on the instance as `editor.*`. The properties below are that same surface, plus the `width`, `placeholder`, `tokens` and `i18n` namespaces the class declares itself.

Last updated Oct 7, 2026 [Edit this page on GitHub](https://github.com/JackUait/blok/blob/main/docs/src/components/api/api-data.ts)

### Reaching the editor instance

The methods below run on the editor you created with new Blok(). They are available once editor.isReady resolves.

TypeScript

```
// You already hold the instance returned by the constructor.
const editor = new Blok({ holder: 'editor' });
await editor.isReady;

// Call any API method on it.
editor.caret.setToLastBlock('end');
```

## Methods

### save()

Promise<OutputData>

Extracts the current editor content as structured JSON data. This is the main method for saving editor content.

Rich text fields, such as `paragraph.text`, hold segments: arrays of `{ text, marks? }` runs. A document saved by an older version can hold HTML strings until it is saved again. `migrateToRichText` converts it.

When to use

Call it after `await editor.isReady`. The returned JSON is your source of truth. Store it and pass it back to `render()`.

Errors

- The editor is in read-only mode when save() is called. Blok's content can not be saved in read-only mode Call `readOnly.set(false)` before saving. You can also save from the last `onSave` payload, or from your own mirrored state.

TypeScript

```
// Save editor content
const data = await editor.save();
console.log(data.blocks); // Array of block data
```

### render(data)

Promise<void>

Renders editor content from previously saved JSON data. It accepts the loose wire shape (`LooseOutputData`). A `null` value for a block's `data`, `id`, or `time` from a backend DTO is normalized at the boundary.

When to use

Loads saved content and replaces the current document. To append instead of replace, use `blocks.insertMany()`.

TypeScript

```
// Load saved content
const savedData = {
  blocks: [
    { id: '1', type: 'paragraph', data: { text: 'Hello' } }
  ]
};
await editor.render(savedData);
```

### focus(atEnd?)

boolean

Sets focus to the editor. It can also put the cursor at the end of the content.

When to use

Pass `true` to place the caret at the very end. For a specific block or offset, use the `caret` API instead.

TypeScript

```
// Focus at start
editor.focus();

// Focus at end
editor.focus(true);
```

### clear()

Promise<void>

Removes all content from the editor. One empty block of the default tool stays behind, so the editor is never block-less. A later save() still returns `blocks: []`. The blank default block does not validate, so it is dropped from the output.

When to use

Removes all blocks and leaves one empty paragraph. You can undo it, unlike `destroy()`, which tears the instance down.

TypeScript

```
// Clear all content
await editor.clear();
```

### destroy()

void

Destroys the editor instance and removes all DOM elements and event listeners.

When to use

Call it from your framework's unmount hook to avoid leaked listeners. The instance is unusable afterwards. Create a new `Blok` to start again.

TypeScript

```
// Clean up on component unmount
editor.destroy();
```

### handlers.set(handlers)

void

Installs, replaces or removes the live editor callbacks in place: `onChange`, `onSave`, `onEnter`, `onSubmit`, `onBeforeRender`, `onAfterRender`. Because the work happens in place, caret, selection, scroll and undo history all survive.

Only the keys you pass are touched. A key whose value is `undefined` UNSETS that handler. That matters because the presence of a callback is itself the semantics.

- An `onSubmit` makes Enter serialize and submit instead of splitting the block.
- An `onSave` arms the change-observation pipeline.

Use it to make a callback reactive without recreating the editor. The React, Vue and Angular adapters drive this setter for you when a prop, listener or `[config]` callback appears or disappears.

When to use

Only the keys you pass are touched. A key set to `undefined` unsets that handler. That is how "Enter sends" is turned back off.

Parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `handlers` | `LiveHandlers` | Required | — | Partial map of live callbacks. Omitted keys are left as they are. A key set to `undefined` unsets that handler. |

TypeScript

```
// "Enter sends" while composing, default Enter while editing a draft
editor.handlers.set({
  onSubmit: sendsOnEnter ? (data) => send(data) : undefined,
});

// Start mirroring content into your store, later stop again
editor.handlers.set({ onSave: (data) => store.set(data) });
editor.handlers.set({ onSave: undefined });
```

### whenAllReady(options?)

Promise<void>

Static method. It resolves once every Blok instance in scope has finished booting, which means each instance's `isReady` has settled. A rejection counts as settled. It is a collective readiness signal for pages that host several instances, and it replaces hand-aggregated per-instance `onReady` callbacks.

- Pass `within` (an Element) to count only instances mounted inside a subtree you own.
  - Then an unrelated editor elsewhere on the page cannot hold your gate closed.
- Pass `settleOn: 'rendered'` to extend readiness from construction to content in the DOM, which also covers re-renders from `render(data)` after boot.

An empty scope resolves right away. Instances that appear while the promise is pending extend the wait. Instances constructed after it resolves are not covered, so call it again, or use `subscribeReady()` for a live signal.

When to use

Call it as `Blok.whenAllReady()` on the class, not on an instance. An instance that is still booting counts in every scope, even when its wrapper is not attached to the document yet. Over-waiting is safe. Under-waiting is a bug.

TypeScript

```
// A comments list: N read-only bodies + a composer.
// Wait only for the editors inside this list.
await Blok.whenAllReady({
  within: listElement,
  settleOn: 'rendered',
});
composer.focus();
```

### readyState(options?)

{ total: number; pending: number; ready: boolean }

Static method. It gives a synchronous readiness snapshot for a scope.

The snapshot says how many instances match `within`. It also says how many are still pending at the requested `settleOn` depth, and whether the scope is settled. An empty scope reports `ready: true`, so you do not need a "nothing to wait for" special case.

When to use

It is cheap enough to call on every notification from `subscribeReady()`. It walks the registered instances and tests DOM containment.

TypeScript

```
const { pending, ready } = Blok.readyState({ within: listElement });

if (!ready) {
  showSkeleton(pending);
}
```

### subscribeReady(listener)

() => void

Static method. It subscribes to readiness changes across all instances (construction, boot, render-state flip, destroy) and returns an unsubscribe function. The listener takes no arguments, so re-read `Blok.readyState(scope)` when it fires. It works with `useSyncExternalStore` and other store adapters, and gives a live signal instead of a one-shot latch.

When to use

In a framework, prefer the adapter wrappers: `useBlokReady()` in @bloklabs/react and @bloklabs/vue, `injectBlokReady()` in @bloklabs/angular. They wrap this subscription and the scope lookup.

TypeScript

```
const unsubscribe = Blok.subscribeReady(() => {
  setReady(Blok.readyState({ within: listElement }).ready);
});

// later
unsubscribe();
```

### createSelector(attr, value?)

string

A named export of the package root, not a member of the Blok class. It builds a CSS selector from a `DATA_ATTR` value.

- With no `value` it produces a presence selector.
- With one it produces an equality selector.

Use it together with `Blok.DATA_ATTR` instead of matching Blok's internal class names, which are not part of the public surface.

TypeScript

```
import { DATA_ATTR, createSelector } from '@bloklabs/core';

createSelector(DATA_ATTR.element); // '[data-blok-element]'
document.querySelectorAll(createSelector(DATA_ATTR.selected, true));
```

### icons

string

Named exports of the `@bloklabs/core/icons` subpath, not members of the Blok class. They are Blok's own glyphs as SVG strings, one `Icon*` constant per glyph (`IconBold`, `IconPlus`, `IconTrash`, `IconWarning`, …).

They are plain strings, so they drop straight into the places a tool must supply markup: a tool's `static get toolbox()` icon and the entries returned by `renderSettings()`. The subpath ships a generated, self-contained declaration file (`types/icons.d.ts`) that lists every constant, so editor autocomplete is the reference for the full set.

TypeScript

```
import { IconBold, IconPlus } from '@bloklabs/core/icons';

class Callout {
  static get toolbox() {
    return { title: 'Callout', icon: IconPlus };
  }

  renderSettings() {
    return [{ icon: IconBold, title: 'Bold text', onActivate: () => this.toggleBold() }];
  }
}
```

## Properties

| Property | Type | Description |
| --- | --- | --- |
| `DATA_ATTR` | `Record<DataAttrKey, DataAttrValue>` | A named export of the package root (`import { DATA_ATTR } from '@bloklabs/core'`), not a property of the editor instance. It holds the stable `data-blok-*` attribute names Blok writes on its DOM. This is the supported way to query editor DOM and write host tests, instead of matching internal class names. The `DataAttrKey` / `DataAttrValue` types and the `createSelector()` helper are exported alongside it. |
| `BLOK_FONT_SIZE_TOKENS` | `BlokFontSizeTokens` | A named export of the package root (`import { BLOK_FONT_SIZE_TOKENS } from '@bloklabs/core'`), not a property of the editor instance. It gives the CSS custom property each `style.fontSize` scenario writes, in a map shaped exactly like the config itself (`BLOK_FONT_SIZE_TOKENS.paragraph`, `.heading[1]`, `.list.checklist`, `.bookmark.link`, …). Use it wherever typography is driven by a channel other than the constructor config: a per-region CSS rule, or `editor.tokens.set({ [BLOK_FONT_SIZE_TOKENS.paragraph]: '18px' })` at runtime. Then the custom property names never have to be hand-copied, and a rename is a compile error instead of a silent no-op. |
| `version` | `string` | A named export of the package root (`import { version } from '@bloklabs/core'`), not a property of the editor instance. It is the running editor version, the same value stamped into `OutputData.version`. |
| `PendingBlok` | `{ isReady; isRendered; destroy(); theme; width; placeholder; tokens; i18n }` | A type exported from the package root (`import type { PendingBlok } from '@bloklabs/core'`), not a property of the editor instance. It is the surface guaranteed to exist synchronously between `new Blok(config)` and `isReady` resolving. Blok builds its module APIs (`blocks`, `caret`, `history`, `readOnly`, …) asynchronously, so reading them earlier returns `undefined`. `PendingBlok` declares only the eight members listed here. That turns the window into a compile error instead of an `undefined` at runtime: `const pending: PendingBlok = new Blok(config); const editor = await pending.isReady;`. |
| `isReady` | `Promise<Blok>` | Promise that resolves with the ready editor instance. The API namespaces below (`blocks`, `caret`, `history`, `readOnly`, …) are built asynchronously. They are `undefined` until it resolves, so type the reference you hold during that window as `PendingBlok`. |
| `isRendered` | `boolean` | Synchronous render-readiness flag. It is true once the current render batch has landed in the DOM, and it mirrors the `data-blok-rendered` wrapper attribute. It is false before the first render and while a re-render is in flight. It complements the async `isReady` and `onReady`: no await or callback is needed, so mount state can be polled synchronously. |
| `blocks` | `Blocks` | Blocks API module |
| `caret` | `Caret` | Caret API module |
| `history` | `History` | History API module |
| `saver` | `Saver` | Saver API module |
| `toolbar` | `Toolbar` | Toolbar API module |
| `inlineToolbar` | `InlineToolbar` | Inline toolbar API module |
| `tools` | `Tools` | Tools API module |
| `uploader` | `Uploader` | Uploader API module for asset uploads routed by asset kind |
| `events` | `Events` | Events API module |
| `listeners` | `Listeners` | Listeners API module |
| `notifier` | `Notifier` | Notifier API module |
| `sanitizer` | `Sanitizer` | Sanitizer API module |
| `selection` | `Selection` | Selection API module |
| `marks` | `Marks` | Marks API module for range-aware inline-mark operations |
| `styles` | `Styles` | Styles API module |
| `tooltip` | `Tooltip` | Tooltip API module |
| `readOnly` | `ReadOnly` | ReadOnly API module |
| `ui` | `Ui` | UI API module |
| `theme` | `Theme` | Theme API module |
| `width` | `Width` | Width API module |
| `placeholder` | `Placeholder` | Placeholder API module |
| `tokens` | `Tokens` | Runtime theme-tokens API module |
| `i18n` | `EditorI18n` | I18n API module. It has everything a tool gets through `api.i18n`, plus `update()` |
| `config` | `Readonly<Pick<BlokConfig, 'linkPaste' | 'link'>>` | Read-only view of selected editor configuration: the `link` and `linkPaste` options this instance was created with. A custom inline or link tool reads the host's link policy from here (as `api.config`) instead of working it out again. |
| `rectangleSelection` | `{ cancelActiveSelection(): void; isRectActivated(): boolean; clearSelection(): void; startSelection(pageX: number, pageY: number, shiftKey?: boolean): void; endSelection(): void }` | Drag-select (rubber-band) control. It is also reachable inside a tool as `api.rectangleSelection`. `startSelection(pageX, pageY, shiftKey?)` begins a rubber-band from page coordinates. `endSelection()` resets the drag state and hides the overlay. `isRectActivated()` reports whether a rubber-band is currently active. `clearSelection()` drops the active flag. `cancelActiveSelection()` aborts a selection in progress (clear + end). Another selection system, for example table cell selection, calls it when it takes priority. |