Column

---
title: Column
docs:
  - route: /docs/components/column-node
    title: Column Nodes
---

<ComponentPreview name="column-demo" />

<PackageInfo>

## Features

- Add columns to your document.
- Choose from a variety of column layouts using `column-group-node` toolbar.
- [ ] Resizable columns

</PackageInfo>

## Kit Usage

<Steps>

### Installation

The fastest way to add column functionality is with the `ColumnKit`, which includes pre-configured `ColumnPlugin` and `ColumnItemPlugin` with [Plate UI](/docs/installation/plate-ui) components.

<ComponentSource name="column-kit" />

- [`ColumnGroupElement`](/docs/components/column-node): Renders column group containers.
- [`ColumnElement`](/docs/components/column-node): Renders individual column items.

### Add Kit

Add the kit to your plugins:

```tsx
import { createPlateEditor } from 'platejs/react';
import { ColumnKit } from '@/components/editor/plugins/column-kit';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...ColumnKit,
  ],
});
```

</Steps>

## Manual Usage

<Steps>

### Installation

```bash
npm install @platejs/layout
```

### Add Plugins

Include the column plugins in your Plate plugins array when creating the editor.

```tsx
import { ColumnPlugin, ColumnItemPlugin } from '@platejs/layout/react';
import { createPlateEditor } from 'platejs/react';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ColumnPlugin,
    ColumnItemPlugin,
  ],
});
```

### Configure Plugins

Configure the plugins with custom components to render column layouts.

```tsx
import { ColumnPlugin, ColumnItemPlugin } from '@platejs/layout/react';
import { createPlateEditor } from 'platejs/react';
import { ColumnGroupElement, ColumnElement } from '@/components/ui/column-node';

const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ColumnPlugin.withComponent(ColumnGroupElement),
    ColumnItemPlugin.withComponent(ColumnElement),
  ],
});
```

- `withComponent`: Assigns [`ColumnGroupElement`](/docs/components/column-node) to render column group containers and [`ColumnElement`](/docs/components/column-node) to render individual columns.

### Turn Into Toolbar Button

You can add this item to the [Turn Into Toolbar Button](/docs/toolbar#turn-into-toolbar-button) to convert blocks into column layouts:

```tsx
{
  icon: <Columns3Icon />,
  label: '3 columns',
  value: 'action_three_columns',
}
```

</Steps>

## Plugins

### `ColumnPlugin`

Add Column Plugin to your document.

### `ColumnItemPlugin`

Add Column Item Plugin to your document.

## Types

### `TColumnGroupElement`

Extends `TElement`.

### `TColumnElement`

Extends `TElement`.

<API name="TColumnElement">
<APIAttributes>
  <APIItem name="width" type="string" optional>
    The column's width (must end with `%`)
  </APIItem>
</APIAttributes>
</API>

## Transforms

### `insertColumnGroup`

Insert a columnGroup with two empty columns.

<API name="insertColumnGroup">
<APIOptions type="InsertNodesOptions & { columns?: number[] | number }">
    - `columns`: Array of column widths or number of equal-width columns (default: 2)
    - Other `InsertNodesOptions` to control insert behavior
  <APIItem name="columns" type="number[] | number" optional>
    Array of column widths or number of equal-width columns (default: 2)
  </APIItem>
  <APIItem name="...InsertNodesOptions" type="InsertNodesOptions">
    Other options to control insert behavior
  </APIItem>
</APIOptions>
</API>

### `insertColumn`

Insert an empty column.

<API name="insertColumn">
<APIOptions type="InsertNodesOptions & { width?: string }">
  <APIItem name="width" type="string" optional>
    Column width (default: "33%")
  </APIItem>
  <APIItem name="...InsertNodesOptions" type="InsertNodesOptions">
    Other options to control insert behavior
  </APIItem>
</APIOptions>
</API>

### `moveMiddleColumn`

Move the middle column to the left or right.

<API name="moveMiddleColumn">
<APIParameters>
  <APIItem name="nodeEntry" type="NodeEntry">
    The node entry of `column` element
  </APIItem>
  <APIItem name="options" type="{ direction: 'left' | 'right' }">
    Control the direction the middle column moves to
  </APIItem>
</APIParameters>

<APIReturns type="boolean">
  Returns `false` if the middle node is empty (and removes it), `true` otherwise.
</APIReturns>
</API>

### `toggleColumnGroup`

Convert a block into a column group layout or update an existing column group's layout.

<API name="toggleColumnGroup">
- If the target block is not a column group, wraps it in a new column group with the specified number of columns
- If the target block is already a column group, updates its column layout using `setColumns`
- The original content becomes the content of the first column
- Additional columns are created with empty paragraphs
<APIOptions type="object">
  <APIItem name="at" type="Location" optional>
    The location to toggle the column group at.
  </APIItem>
  <APIItem name="columns" type="number" optional>
    Number of equal-width columns to create (default: 2)
  </APIItem>
  <APIItem name="widths" type="string[]" optional>
    Array of column widths (e.g., ['50%', '50%']). Takes precedence over `columns`.
  </APIItem>
</APIOptions>
</API>

### `setColumns`

Update the column layout of an existing column group.

<API name="setColumns">
- When increasing columns:
  - Keeps existing column content
  - Adds new empty columns with specified widths
- When decreasing columns:
  - Merges content from removed columns into the last remaining column
  - Updates widths of remaining columns
- When keeping same number of columns:
  - Only updates column widths
<APIOptions type="object">
  <APIItem name="at" type="Path">
    The path to the column group element.
  </APIItem>
  <APIItem name="columns" type="number" optional>
    Number of equal-width columns to create.
  </APIItem>
  <APIItem name="widths" type="string[]" optional>
    Array of column widths (e.g., ['33%', '67%']). Takes precedence over `columns`.
  </APIItem>
</APIOptions>
</API>


## Hooks

### `useDebouncePopoverOpen`

<API name="useDebouncePopoverOpen">
<APIReturns type="boolean">
  Whether the popover is open.
</APIReturns>
</API>