blocknote

# BlockNote

Skill for working with [BlockNote](https://www.blocknotejs.org/), a block-based rich text editor for React.

## Core Mental Model

Everything in a BlockNote document is a **Block**. A paragraph is a block, a heading is a block, a list item is a block. Blocks can nest (children), and each block holds its rich text as an array of **InlineContent** objects.

```
Document
├── Block (paragraph)          ← top-level block
│   └── InlineContent[]        ← rich text inside
├── Block (heading)
│   └── InlineContent[]
└── Block (bulletListItem)
    ├── InlineContent[]
    └── Block (nested child)   ← indented sub-item
        └── InlineContent[]
```

## Block Type

```ts
type Block = {
  id: string;
  type: string;                                        // "paragraph" | "heading" | "bulletListItem" | ...
  props: Record<string, boolean | number | string>;    // type-specific properties
  content: InlineContent[] | TableContent | undefined; // rich text (undefined for images, columns)
  children: Block[];                                   // nested child blocks
};
```

When creating or updating blocks, use `PartialBlock` — all fields are optional:

```ts
editor.insertBlocks([{ type: "paragraph", content: "Hello!" }], refBlock);
editor.updateBlock(blockId, { props: { level: 2 } });
```

## InlineContent Types

```ts
type StyledText = { type: "text"; text: string; styles: Styles };
type Link      = { type: "link"; content: StyledText[]; href: string };
type InlineContent = StyledText | Link | CustomInlineContent;
```

`Styles` is a key/value map of active style attributes (e.g. `{ bold: true, textColor: "red" }`).

See [references/document-structure.md](references/document-structure.md) for full type definitions including `TableContent` and column blocks.

## Quick API Reference

### Reading

```ts
const all   = editor.document;                         // all top-level blocks
const block = editor.getBlock(id);                     // by id or Block ref
const prev  = editor.getPrevBlock(id);
const next  = editor.getNextBlock(id);
const parent = editor.getParentBlock(id);

editor.forEachBlock((block) => {
  console.log(block.id, block.type);
  return true;                                         // false stops traversal
});
```

### Inserting

```ts
// Insert before (default) or after a reference block
editor.insertBlocks(
  [{ type: "heading", content: "Title", props: { level: 2 } }],
  referenceBlock,
  "after",
);
```

### Updating

```ts
editor.updateBlock(blockId, { type: "heading", props: { level: 1 } });
editor.updateBlock(blockId, { content: "New text" });
```

### Removing & Replacing

```ts
editor.removeBlocks([id1, id2]);
editor.replaceBlocks([oldId], [{ type: "paragraph", content: "Replacement" }]);
```

### Moving & Nesting

```ts
editor.moveBlocksUp();
editor.moveBlocksDown();
if (editor.canNestBlock())   editor.nestBlock();
if (editor.canUnnestBlock()) editor.unnestBlock();
```

### Inline Content at Cursor

```ts
editor.insertInlineContent("plain text");
editor.insertInlineContent([
  { type: "text", text: "Bold", styles: { bold: true } },
  { type: "link", content: "BlockNote", href: "https://blocknotejs.org" },
]);
```

### Styles on Selection

```ts
editor.addStyles({ bold: true, textColor: "red" });
editor.removeStyles({ bold: true });
editor.toggleStyles({ italic: true });
const active = editor.getActiveStyles();               // styles at cursor / selection end
const text   = editor.getSelectedText();
```

### Links

```ts
editor.createLink("https://example.com");             // wraps selected text
editor.createLink("https://example.com", "Custom label");
const url = editor.getSelectedLinkUrl();
```

### Cursor & Selection

```ts
const pos = editor.getTextCursorPosition();           // { block, prevBlock, nextBlock, ... }
editor.setTextCursorPosition(blockId, "start");       // "start" | "end"
const sel = editor.getSelection();
editor.setSelection(startBlockId, endBlockId);
```

See [references/block-api.md](references/block-api.md) for the complete API reference with all parameters and examples.

## Common Patterns

### Insert block after the current cursor position

```ts
const { block } = editor.getTextCursorPosition();
editor.insertBlocks(
  [{ type: "paragraph", content: "Inserted after cursor" }],
  block,
  "after",
);
```

### Convert the current block to a heading

```ts
const { block } = editor.getTextCursorPosition();
editor.updateBlock(block, { type: "heading", props: { level: 2 } });
```

### Build a section programmatically

```ts
const anchor = editor.document[0];
editor.insertBlocks(
  [
    { type: "heading", content: "Section Title", props: { level: 2 } },
    { type: "paragraph", content: "Intro paragraph." },
    { type: "bulletListItem", content: "Item 1" },
    { type: "bulletListItem", content: "Item 2" },
  ],
  anchor,
  "after",
);
```

### Apply bold to selected text

```ts
editor.addStyles({ bold: true });
```

### Collect all blocks of a given type

```ts
const headings: Block[] = [];
editor.forEachBlock((block) => {
  if (block.type === "heading") headings.push(block);
  return true;
});
```

### Replace a block with a different type, preserving content

```ts
const block = editor.getBlock(blockId)!;
editor.replaceBlocks([block], [{ type: "heading", content: block.content, props: { level: 1 } }]);
```

## Key Gotchas

- **`content` can be `undefined`**: Image blocks, column blocks, and `columnList` blocks have no rich-text content — their `content` field is `undefined`. Always check before accessing.
- **`children` vs `content`**: Nested sub-blocks live in `children`, not `content`. `content` is only the inline rich text of the block itself.
- **`editor.document` is a snapshot**: It returns the document state at the time of the call. Subscribe to `onChange` to keep a reactive copy.
- **`PartialBlock` for writes**: When inserting or updating you never need to supply all fields. Omit anything you don't want to change.
- **`forEachBlock` is depth-first**: It traverses the entire tree including nested children, not just top-level blocks.
- **Column restrictions**: `columnList` children must be `column` blocks; `column` children must be regular blocks; a `columnList` needs at least 2 columns.
- **`moveBlocksUp/Down` acts on the selection**: Position the cursor or set a selection before calling these.