---
title: Blocks
description: The document editor behind Pages and the CMS, for any app: paragraphs, headings, lists, tables, charts and articles.
section: Plugins
order: 20
---

# Blocks

The document editor behind Pages and the CMS, for any app: paragraphs, headings, lists, tables, charts and articles.

The `blocks` plugin edits and shows a document made of blocks. Pages and the CMS install it for you. To add it yourself:

```sh title="Terminal"
sluurp plugin add blocks
```

Features include:

- Text, three sizes of heading, bulleted, numbered and to-do lists, quotes, callouts, code and maths
- Tables, grids, charts from a collection, figures, pull quotes and a page's contents
- Typing shortcuts as you would expect: `#` for a heading, `-` for a list, `[]` for a to-do, `/` for the menu of blocks
- Articles set in columns, with lines that run round their pictures
- Kinds of block added by other plugins, such as a whiteboard with [Board](/docs/board)

There is nothing to set up in the admin.

## Set it up once

The editor speaks through your app: its words, its addresses, its messages. Tell it how, once, when your app starts:

```ts title="app.ts"
import { configurePages, blocksTranslations } from "plugin:blocks";

i18n.add(blocksTranslations); // its words, in English, French, Romanian and German

configurePages({
  client: sluurp,
  me: () => currentUser(),
  t: (key, vars) => i18n.t(key, vars),
  href: (route, id) => `#/${route}${id ? `/${id}` : ""}`,
  detail: () => currentPageId(),
  notify: (message) => toast(message),
  complain: (error) => toast.error(String(error)),
});
```

With Pages installed, call Pages' own `configurePages` and add `pagesTranslations` instead: they set up the block editor as well.

## Edit a document

```tsx title="note.tsx"
import { BlockEditor } from "plugin:blocks";

<BlockEditor blocks={note.blocks} editable onChange={(blocks) => save({ blocks })} table={() => null} />
```

`blocks` is the document as you saved it: an array, kept wherever your app keeps it, such as a JSON field. `onChange` gets the whole array a moment after anything changes. With `editable={false}` the same component shows the document read-only.

`table` draws a table block. A page that has tables passes its own renderer; otherwise return nothing. Pass `page`, the document's id, to make what is on it live for everyone looking at it, such as a whiteboard.

## Add a kind of block

Another plugin can add a kind of block, offered in the `/` menu once it is installed. [Board](/docs/board) adds a whiteboard this way:

```ts title="sticker.ts"
import { addBlockKind } from "plugin:blocks";

addBlockKind({
  type: "sticker",
  key: "sticker.name", // its name in the menu, a key of your app's words
  icon: '<circle cx="12" cy="12" r="10"/>',
  make: () => ({ type: "sticker", text: "" }),
  view: Sticker, // drawn with { block, editable, page, onChange }
});
```

A document that holds a kind of block whose plugin isn't installed shows a notice in its place, and keeps the block as it is.
