FrameworkJavaScript

Blok configuration options

The configuration object passed to the Blok constructor. It is formally split into two types: `BlokMountOptions` — options fixed for the instance's life (holder, tools, i18n, callbacks, …) — and `BlokState`, the LIVE fields: `readOnly` (including `hideControls`), `hideToolbar`, and `inlineToolbar`. Every `BlokState` field maps to a documented runtime setter (`readOnly.set`, `toolbar.setHidden`, `tools.setInlineToolbar`), so changing it never requires recreating the editor — and the React, Vue and Angular adapters react to these props/inputs in place. `BlokConfig = BlokMountOptions & BlokState`, so existing code compiles unchanged.

Edit this page on GitHub

TypeScript

import { Blok, type BlokConfig } from '@bloklabs/core';

const config: BlokConfig = {
  holder: 'editor',
  placeholder: 'Start writing...',
  autofocus: true,
  readOnly: false,
  minHeight: 300,
};

const editor = new Blok(config);

Configuration

Option	Type	Default	Description
`holder`	`string \| HTMLElement`	`'blok'`	Container element ID or reference
`tools`	`Record<string, ToolConstructable \| ToolSettings>`	`{}`	Available block and inline tools
`placeholder`	`string \| false`	`false`	Placeholder text shown in the first block when the editor is empty; false disables it
`minHeight`	`number`	`300`	Height in px of the editor's bottom clickable zone
`defaultBlock`	`string`	`'paragraph'`	Default block type
`data`	`OutputData \| LooseOutputData`	`undefined`	Initial data to render. The loose wire shape is accepted: `null` values for block `data`, `id`, or `time` (common in backend DTOs) are normalized at the boundary.
`readOnly`	`boolean \| { hideControls: boolean }`	`false`	Enable read-only mode. Pass `{ hideControls: true }` to also hide the hover toolbar, block settings, and inline toolbar. Live: change at runtime via `readOnly.set(state, { hideControls })` — the same instance flips modes in place, preserving caret, undo history and scroll.
`onChange`	`(api: API, event: BlockMutationEvent \| BlockMutationEvent[]) => void`	`undefined`	Change callback function; the event argument carries the mutation(s) that occurred (batched into an array when several fire at once)
`onSave`	`(data: OutputData, api: API) => void`	`undefined`	Reactive save callback — fires automatically with the full serialized content on every debounced content change, so you don't have to call save() by hand.
`onReady`	`(blok?: Blok) => void`	`undefined`	Fires once when the editor becomes ready, receiving the fully-initialized Blok instance
`onEnter`	`(event: KeyboardEvent, api: API) => boolean \| void`	`undefined`	Fires when Enter is pressed in a block, before Blok splits it or creates a new one. Return true to mark it handled — Blok suppresses its default block split/create (the native newline is still prevented). Never fires for Shift+Enter, tools with enableLineBreaks, or while a popover/toolbar owns Enter. Ideal for chat inputs ("Enter sends") — pair with the paragraph tool's preserveBlank config instead of subclassing Paragraph.
`autofocus`	`boolean`	`false`	If true, sets the caret in the first block once the editor is ready
`inlineToolbar`	`string[] \| boolean`	`true`	Default inline toolbar for all tools; an array restricts it to the listed inline tools, false disables it. Live: reconfigure at runtime via `tools.setInlineToolbar(config)`.
`hideToolbar`	`boolean`	`false`	Hide the hover block toolbar (plus button / drag handle) and collapse the editor gutter reserved for it; the keyboard "/" menu keeps working. Live: flip at runtime via `toolbar.setHidden(hidden)`.
`i18n`	`I18nConfig`	`undefined`	Internationalization config (locale + message dictionary). Live: switch language at runtime via `i18n.update({ locale, messages })` — the editor relabels in place, so caret and undo history survive (`defaultLocale` stays mount-only).
`theme`	`'auto' \| 'light' \| 'dark'`	`'auto'`	Color theme; 'auto' follows the OS preference via prefers-color-scheme