# Blok

> Blok is a headless block-based rich text editor for React, Vue, and Angular that stores content as typed JSON instead of HTML.

## Site

- [Build beautiful block-based editors](https://blokeditor.com/): Blok is a headless block-based rich text editor for React, Vue, and Angular that stores content as typed JSON instead of HTML.
- [Try the Editor](https://blokeditor.com/demo/): Try Blok in the browser: slash commands, tables, columns, drag and drop, and the JSON it produces.
- [Blok documentation](https://blokeditor.com/docs/): Guides, API reference, and 29 built-in block and inline tools for Blok. Start in five minutes.
- [Storage presets](https://blokeditor.com/presets/): Ready-made uploaders for Blok: Supabase, S3-compatible storage, Cloudinary, and IndexedDB — no backend to write for file uploads.
- [Uploads and link previews](https://blokeditor.com/server/): Three ways to give Blok file uploads and link previews: storage you already have, a container beside your app, or the service on its own host.
- [Outgrown Editor.js?](https://blokeditor.com/migration/): Migration guides and a codemod for moving an existing editor integration to Blok without rewriting stored content.
- [Migration reference](https://blokeditor.com/migration/reference/): The complete reference: renamed APIs, plugin equivalents, CSS variable mappings, and verification steps.
- [Changelog](https://blokeditor.com/changelog/): Every Blok release with its features, fixes, and breaking changes. Currently on 1.12.0.

## Getting started

- [Get started with Blok in five minutes](https://blokeditor.com/docs/quick-start/): Install the package, mount an editor, and save JSON output. Copy-paste setup for JavaScript, React, Vue, and Angular.
- [Build your first Blok editor](https://blokeditor.com/docs/tutorial/): Step by step: mount the editor, register tools, persist blocks, and reload saved content into a fresh instance.
- [Everything is a block: Blok's data model](https://blokeditor.com/docs/concepts/): How Blok stores content as nested JSON blocks with parentId and contentIds, and why there is no HTML in the document.
- [How to create a custom block tool in Blok](https://blokeditor.com/docs/custom-block-tool/): Implement the BlockTool interface: render, save, validate, toolbox, pasteConfig, and sanitize, with a working example.

## Core

- [The Blok class: create and destroy an editor](https://blokeditor.com/docs/core/): Create, await, and tear down an editor instance, and what is safe to call before isReady resolves.
- [Blok configuration options](https://blokeditor.com/docs/config/): Every configuration option: holder, tools, data, placeholder, readOnly, i18n, and the style tokens.
- [Blocks API: insert, move, delete, and render blocks](https://blokeditor.com/docs/blocks-api/): Insert, move, delete, convert, and render blocks programmatically, including nested blocks and markdown insertion.
- [BlockAPI: work with a single block](https://blokeditor.com/docs/block-api/): Work with a single block: read its id and name, get its holder element, save it, and dispatch tool events.
- [Saver API: serialize the editor to JSON](https://blokeditor.com/docs/saver-api/): Serialize the editor to JSON, what save() returns, and when the promise it hands back resolves.
- [View renderer: display documents without an editor](https://blokeditor.com/docs/view-api/): Render OutputData to sanitized HTML or plain text with blocksToHtml — DOM-free, SSR-safe, no editor instance — plus BlokView and useBlokView for React.

## Editing

- [Caret API: move, focus, and set cursor position](https://blokeditor.com/docs/caret-api/): Move the caret, focus a block, and read the cursor position without touching the DOM directly.
- [Selection API: read and set the selection](https://blokeditor.com/docs/selection-api/): Read and manipulate the current selection, including selections that span more than one block.
- [Marks API: range-aware inline formatting](https://blokeditor.com/docs/marks-api/): Apply, read, and toggle inline marks across the whole selection with editor.marks — range-aware splitting, in-place updates, and derived sanitizer rules.
- [Styles API: the class names tools should use](https://blokeditor.com/docs/styles-api/): The CSS class names Blok exposes so a custom tool can style itself consistently with the editor.
- [History API: undo, redo, and transactions](https://blokeditor.com/docs/history-api/): Undo and redo programmatically, and group several operations into a single undoable transaction.

## Interface

- [Toolbar API: control the block toolbar](https://blokeditor.com/docs/toolbar-api/): Open, close, and toggle the block toolbar and its settings menu from your own code.
- [Inline Toolbar API: control the formatting toolbar](https://blokeditor.com/docs/inline-toolbar-api/): Show or hide the inline formatting toolbar from your own code, and react to selection changes.
- [UI API: reach the editor's DOM nodes](https://blokeditor.com/docs/ui-api/): Access the editor's DOM nodes: the wrapper, the redactor, and the holder of the current block.
- [Notifier API: show notifications](https://blokeditor.com/docs/notifier-api/): Show success, error, and confirmation notifications from inside a tool or from host code.
- [Tooltip API: tooltips for your own tool UI](https://blokeditor.com/docs/tooltip-api/): Attach tooltips to your own tool UI using the editor's own tooltip implementation.
- [Theme API: switch light, dark, and auto](https://blokeditor.com/docs/theme-api/): Read and switch the editor's light, dark, or auto theme at runtime, and resolve what auto currently evaluates to.
- [Width API: narrow and full editor layouts](https://blokeditor.com/docs/width-api/): Read, set, and toggle the editor's content width between the default narrow column and the full width of its container.
- [Placeholder API: change the placeholder at runtime](https://blokeditor.com/docs/placeholder-api/): Change the empty-block placeholder at runtime; it updates existing blocks in place and applies to blocks created afterward.

## Extending & system

- [Tools API: register and update tools](https://blokeditor.com/docs/tools-api/): Register tools, update the toolbox at runtime, and read back which tools are currently available.
- [Uploader API: upload assets by kind](https://blokeditor.com/docs/uploader-api/): Route file and URL uploads by asset kind, so an audio block’s cover art reaches your image pipeline instead of your audio endpoint.
- [Events API: subscribe to editor events](https://blokeditor.com/docs/events-api/): Subscribe to editor events, emit your own, and the full list of events Blok itself dispatches.
- [Listeners API: leak-free DOM listeners](https://blokeditor.com/docs/listeners-api/): Attach DOM listeners that Blok removes for you when the editor is destroyed, so a tool cannot leak.
- [Sanitizer API: how content is cleaned](https://blokeditor.com/docs/sanitizer-api/): How Blok sanitizes stored and pasted content, and how to declare a tool's own sanitizer config.
- [Read-only API: toggle editing on and off](https://blokeditor.com/docs/readonly-api/): Toggle read-only mode at runtime, and what a tool must implement for the switch to work in place.
- [i18n API: translate Blok's interface](https://blokeditor.com/docs/i18n-api/): Supply translations for tool names, toolbar labels, and the accessibility strings Blok renders.
- [Dev override seam: threat model and opt-out](https://blokeditor.com/docs/dev-override-seam/): Why every published entry checks globalThis.__BLOK_DEV_OVERRIDE__ before falling back to the bundled code, and how to disable it.

## Data types

- [OutputData: Blok's saved JSON format](https://blokeditor.com/docs/output-data/): The exact shape save() returns: time, version, and the blocks array with id, type, data, tunes, parentId, and contentIds.
- [BlockData: the per-block payload](https://blokeditor.com/docs/block-data/): What lives inside a block's data field, how tunes attach to it, and how parentId and contentIds express nesting.

## Framework adapters

- [The BlokEditor React component](https://blokeditor.com/docs/blok-editor/): Every prop on BlokEditor: data, tools, onChange, onSave, readOnly, onReady, and the imperative ref API.
- [useBlocks(): read and mutate blocks from React](https://blokeditor.com/docs/use-blocks/): Read and mutate blocks from React with useBlocks, including insert, move, and subtree relocation.
- [useBlokReady(): scoped editor readiness](https://blokeditor.com/docs/use-blok-ready/): Wait for the Blok editors inside one container to finish rendering, with useBlokReady — scoped, reactive, and safe for empty lists.

## Block tools

- [Paragraph block: Blok's default text block](https://blokeditor.com/docs/paragraph/): The default text block: inline formatting, markdown shortcuts, colour presets, and the text field it saves.
- [Header block: headings H1 to H6](https://blokeditor.com/docs/header/): Headings H1 to H6 with markdown shortcuts, anchor ids, and level conversion from the block settings menu.
- [List block: ordered, unordered, and checklists](https://blokeditor.com/docs/list/): Nested ordered, unordered, and checklist items, with Tab and Shift-Tab indentation and lossless list paste.
- [Table block: merged cells and rich cell content](https://blokeditor.com/docs/table/): Tables with merged cells, per-cell rich content, and lossless paste from Excel, Google Docs, and Notion.
- [Toggle block: collapsible content](https://blokeditor.com/docs/toggle/): A collapsible block that owns child blocks through contentIds, including toggle headings that keep their level.
- [Callout block: highlighted notes](https://blokeditor.com/docs/callout/): Highlighted note blocks with an icon and a colour preset, for warnings, tips, and asides inside a document.
- [Database block: schema, views, and rows](https://blokeditor.com/docs/database/): A database is a block: its schema and view configs live in data, and every row is a child block of it.
- [Database row block: properties and page body](https://blokeditor.com/docs/database-row/): Each row is a block whose data.properties conforms to the parent database's schema, with child blocks as its page body.
- [Divider block: a horizontal rule](https://blokeditor.com/docs/divider/): A horizontal rule block, the markdown shortcut that creates it, and the empty payload it saves.
- [Spacer block: adjustable vertical space](https://blokeditor.com/docs/spacer/): A resizable vertical space block for controlling page rhythm, and the height it stores in its data.
- [Quote block: blockquotes with captions](https://blokeditor.com/docs/quote/): Blockquotes with an optional caption and alignment, preserving inline links and formatting on paste.
- [Code block: syntax-highlighted code](https://blokeditor.com/docs/code/): Fenced code with syntax highlighting, a language picker, and copy support, plus the code and language it saves.
- [Image block: uploads, captions, and resizing](https://blokeditor.com/docs/image/): Upload, paste, or link images, with resizing, captions, client-side compression, and an enforced size limit.
- [Columns block: multi-column layout](https://blokeditor.com/docs/column_list/): A row of resizable columns, where each column is itself a block that owns its own children.
- [Column block: one column of a layout](https://blokeditor.com/docs/column/): A single column inside a column list, carrying a width fraction and its own list of child blocks.
- [Embed block: responsive third-party embeds](https://blokeditor.com/docs/embed/): Paste a URL from a supported service and get a responsive embed, with a resizable height and a service registry.
- [Bookmark block: rich link previews](https://blokeditor.com/docs/bookmark/): Turn a URL into a rich link card with a title, description, and favicon, degrading gracefully when metadata is missing.
- [File block: attachments and downloads](https://blokeditor.com/docs/file/): Attach arbitrary files with a download affordance, a file name, and size metadata stored on the block.
- [Audio block: an inline audio player](https://blokeditor.com/docs/audio/): Upload or link audio and render an inline player, including share links from the common hosting services.
- [Video block: uploads and embedded players](https://blokeditor.com/docs/video/): Upload video or embed a player, with automatic GIF to WebM conversion and a generous upload size limit.

## Inline tools

- [Bold: strong emphasis in Blok](https://blokeditor.com/docs/bold/): Make a selection bold from the inline toolbar or with Cmd/Ctrl+B, and the markup it writes into block text.
- [Italic: emphasised text in Blok](https://blokeditor.com/docs/italic/): Italicise a selection from the inline toolbar or with Cmd/Ctrl+I, and the markup it writes into block text.
- [Link tool: insert and edit inline links](https://blokeditor.com/docs/link/): Insert and edit links, control target behaviour, and configure the hover card and the link edit menu.
- [Marker: highlight text with colour](https://blokeditor.com/docs/marker/): Highlight a selection with the marker tool, pick a colour, and see the markup it stores in the block.
- [Underline: underlined text in Blok](https://blokeditor.com/docs/underline/): Underline a selection from the inline toolbar or with Cmd/Ctrl+U, and the markup it stores in block text.
- [Strikethrough: crossed-out text in Blok](https://blokeditor.com/docs/strikethrough/): Strike through a selection from the inline toolbar, and the markup Blok stores inside the block's text field.
- [Inline code: monospace code spans](https://blokeditor.com/docs/inlineCode/): Mark a selection as inline code with Cmd/Ctrl+E, and the markup it stores inside a block's text field.
- [Equation tool: inline LaTeX math](https://blokeditor.com/docs/equation/): Write inline math with LaTeX syntax, and how equations are stored and sanitized inside a block.
- [Clear format: strip inline styling](https://blokeditor.com/docs/clearFormat/): Remove every inline mark from a selection in one action, leaving plain text without touching block structure.
- [Superscript & subscript: raised and lowered text](https://blokeditor.com/docs/supSub/): Toggle superscript or subscript from one toolbar button or with Cmd/Ctrl+Period and Cmd/Ctrl+Comma, and the sup/sub markup Blok stores.