# Layout tables

<!-- AI-AGENT-NOTE: An interactive demo is embedded here but is not represented in this Markdown file. If you need to see it in action, open this page in a browser (e.g. via a browser-automation MCP like Chrome DevTools or Playwright), or let the user know a live demo is available on this page. -->

Layout tables are used to structure web page content spatially rather than for presenting tabular data. They allow integrators to create multi-column designs and precise positioning of elements on a page. This kind of functionality may be handy, for example, when preparing newsletter content. You can switch between [content tables](tables.md) and layout tables by using the table toggling feature.

> **Unlock this feature with selected CKEditor Plans**
>
> Try all premium features – no credit card needed.
>
> [Sign up for a free trial ](https://portal.ckeditor.com/checkout?plan=free)[Select a Plan](https://ckeditor.com/pricing/)

<a id="table-types-comparison">

## Table types comparison

The CKEditor 5 table feature offers several approaches and plugins responsible for the execution of tables. These include:

* [Regular content tables](tables.md) – Content tables provide the basic table experience for presentation of tabular data.
* [Table layout](layout-tables.md) – Layout tables are used to structure the content spatially rather than present content. They allow for creating multi-column designs and precise positioning of elements on a page.
* [Plain table output](../../api/module_table_plaintableoutput-PlainTableOutput.md) – This plugin strips the `<figure>` tag from the table data. It is basically an email client compatibility feature.

|                  | Regular table                                 | Layout table                                       | Plain table output                                  |
| ---------------- | --------------------------------------------- | -------------------------------------------------- | --------------------------------------------------- |
| Usage            | Used for presenting tabular data              | Used for creating layouts and multi-column designs | Stripped of `<figure>` tags for email compatibility |
| Purpose          | Rich formatting and tabular data presentation | Focused on content positioning and structure       | Simplified output for maximum interoperability      |
| Setup            | Default table type in CKEditor 5              | Available through toggling or direct insertion     | Available as an optional plugin                     |
| Markup influence | Affects editing view and output data          | Affects editing view and output data               | Affects only output data                            |

<a id="demo">

## Demo

Check the editor below to see the layout tables plugin in action. Use the layout table toolbar button to insert a new layout table.

<!-- AI-AGENT-NOTE: An interactive demo is embedded here but is not represented in this Markdown file. If you need to see it in action, open this page in a browser (e.g. via a browser-automation MCP like Chrome DevTools or Playwright), or let the user know a live demo is available on this page. -->

This demo presents a limited set of features. Visit the [feature-rich editor example](../../examples/builds-custom/full-featured-editor.md) to see more in action.

<a id="table-toggling">

## Table toggling

There are several table types available in CKEditor 5. To switch between these different table modes, you can use the table toggling feature. It allows users to change the type of an existing table by clicking it and selecting the desired table type. This enables seamless switching between presentation-focused content tables and layout-oriented tables without recreating the structure from scratch.

When a table is selected, you can toggle its type in one of two ways:

1. If the [`TableProperties`](../../api/module_table_tableproperties-TableProperties.md) plugin is enabled, the table properties button will include a “Table type” dropdown option that allows switching between regular content tables and layout tables.

2. If the [`TableProperties`](../../api/module_table_tableproperties-TableProperties.md) plugin is not available, you can use the dedicated `tableType` toolbar button to change the table type.

Switching between table types preserves the content while adjusting the table’s behavior and styling to match its new purpose. Layout tables focus on spatial arrangement and design, while content tables emphasize data presentation.

> **Warning**
>
> Changing a regular table to a layout table may result in data loss. Table captions will be removed when converting to a layout table, as layout tables do not support them.

<a id="installation">

## Installation

After [installing the editor](../../getting-started/installation/cloud/quick-start.md), add the feature to your plugin list and toolbar configuration:

**NPM**

```js
import { ClassicEditor, Table, TableLayout } from 'ckeditor5';

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		plugins: [ Table, TableLayout, /* ... */ ],
		toolbar: [ 'insertTable', 'insertTableLayout', /* ... */ ],
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

**CDN**

```js
const { ClassicEditor, Table, TableLayout } = CKEDITOR;

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ Table, TableLayout, /* ... */ ],
		toolbar: [ 'insertTable', 'insertTableLayout', /* ... */ ],
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

<a id="configuration">

## Configuration

<a id="configuring-the-preferred-type-for-loading-external-tables">

### Configuring the preferred type for loading external tables.

By default, external tables are loaded using internal heuristics. This can be configured by setting the preferred table type for loading all external tables by setting the [`config.table.tableLayout.preferredExternalTableType`](../../api/module_table_tableconfig-TableLayoutConfig.md#member-preferredExternalTableType) option to `content` or `layout`.

**NPM**

```js
import { ClassicEditor, Table, TableLayout } from 'ckeditor5';

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		plugins: [ Table, TableLayout /* ... */ ],
		table: {
			tableLayout :{
				preferredExternalTableType: 'content' // or 'layout'
			}
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

**CDN**

```js
const { ClassicEditor, Table, TableLayout } = CKEDITOR;

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ Table, TableLayout /* ... */ ],
		table: {
			tableLayout :{
				preferredExternalTableType: 'content' // or 'layout'
			}
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

<a id="stripping-the-figure-wrapper-from-content-tables">

### Stripping the `<figure>` wrapper from content tables

By default, the `<figure>` wrapper is preserved on content tables. To strip the `<figure>` element, set the [`config.table.tableLayout.stripFigureFromContentTable`](../../api/module_table_tableconfig-TableLayoutConfig.md#member-stripFigureFromContentTable) option to `true`.

**NPM**

```js
import { ClassicEditor, Table, TableLayout } from 'ckeditor5';

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		plugins: [ Table, TableLayout /* ... */ ],
		table: {
			tableLayout :{
				stripFigureFromContentTable: true // or false
			}
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

**CDN**

```js
const { ClassicEditor, Table, TableLayout } = CKEDITOR;

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ Table, TableLayout /* ... */ ],
		table: {
			tableLayout :{
				stripFigureFromContentTable: true // or false
			}
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

<a id="configuring-the-table-toggle-feature">

### Configuring the table toggle feature

To configure the table toggling feature, you have several options:

1. Include the [`TableLayout`](../../api/module_table_tablelayout-TableLayout.md) plugin in your editor setup to enable toggling between table types.
2. Add the `tableType` button to your table content toolbar if you want a dedicated button for toggling.
3. For advanced UI integration scenarios, include both [`TableProperties`](../../api/module_table_tableproperties-TableProperties.md) and [`TableToolbar`](../../api/module_table_tabletoolbar-TableToolbar.md) plugins, which will add the table type option to the table properties dropdown.

The table type can also be set programmatically through the editor’s API, making it suitable for integration with external controls or automated workflows.

<a id="configuring-table-toggle-with-tableproperties">

### Configuring table toggle with `TableProperties`

When the [`TableProperties`](../../api/module_table_tableproperties-TableProperties.md) plugin is available, table type options will be integrated into the table properties dropdown:

**NPM**

```js
import { ClassicEditor, Table, TableLayout, TableProperties, TableToolbar } from 'ckeditor5';

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		plugins: [ Table, TableLayout, TableProperties, TableToolbar, /* ... */ ],
		toolbar: [ 'insertTable', 'insertTableLayout', /* ... */ ],
		table: {
			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells', 'tableProperties' ]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

**CDN**

```js
const { ClassicEditor, Table, TableLayout, TableProperties, TableToolbar } = CKEDITOR;

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ Table, TableLayout, TableProperties, TableToolbar, /* ... */ ],
		toolbar: [ 'insertTable', 'insertTableLayout', /* ... */ ],
		table: {
			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells', 'tableProperties' ]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

This will add table toggling button to the table toolbar:

<a id="configuring-table-toggle-without-tableproperties">

### Configuring table toggle without `TableProperties`

If the `TableProperties` plugin is not available, you can use the dedicated `tableType` button in the content toolbar to change table types:

**NPM**

```js
import { ClassicEditor, Table, TableLayout, TableToolbar } from 'ckeditor5';

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		plugins: [ Table, TableLayout, TableToolbar, /* ... */ ],
		toolbar: [ 'insertTable', 'insertTableLayout', /* ... */ ],
		table: {
			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells', 'tableType', /* ... */  ]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

**CDN**

```js
const { ClassicEditor, Table, TableLayout, TableToolbar } = CKEDITOR;

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ Table, TableLayout, TableToolbar, /* ... */ ],
		toolbar: [ 'insertTable', 'insertTableLayout', /* ... */ ],
		table: {
			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells', 'tableType', /* ... */  ]
		}
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

<a id="configuring-table-toggle-in-the-main-editor-toolbar">

### Configuring table toggle in the main editor toolbar

You can configure the main editor toolbar to use the content and layout tables selector dropdown. This is handy if for some reason you do not want to use the table toolbar in your implementation.

**NPM**

```js
import { ClassicEditor, Table, TableLayout } from 'ckeditor5';

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		plugins: [ Table, TableLayout, /* ... */ ],
		toolbar: [ 'insertTable', 'insertTableLayout', 'tableType', /* ... */ ]
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

**CDN**

```js
const { ClassicEditor, Table, TableLayout } = CKEDITOR;

ClassicEditor
	.create( {
		licenseKey: '<YOUR_LICENSE_KEY>',
		plugins: [ Table, TableLayout, /* ... */ ],
		toolbar: [ 'insertTable', 'insertTableLayout', 'tableType', /* ... */ ]
	} )
	.then( /* ... */ )
	.catch( /* ... */ );
```

This will add table toggling button to the main editor toolbar:

> **Note**
>
> Please note that the layout toggle button does not insert new tables, it just toggles the type. You still need to configure the table insertion buttons, as shown above.

<a id="related-features">

## Related features

There are other CKEditor 5 features you may want to check:

* [Email editing](../email-editing/email.md) – The email editing solution is a set of tools aimed at making the email composition a better and more effective experience.
* [Email configuration helper](../email-editing/email-configuration-helper.md) – The email configuration helper plugin is the best way to start writing and editing emails.

<a id="common-api">

## Common API

The [`TableLayout`](../../api/module_table_tablelayout-TableLayout.md) plugin registers the following command:

* [`TableLayoutEditing`](../../api/module_table_tablelayout_tablelayoutediting-TableLayoutEditing.md) – The layout table editing command.
* [`TableLayoutUI`](../../api/module_table_tablelayout_tablelayoutui-TableLayoutUI.md) – The layout table UI.
* [`InsertTableLayoutCommand`](../../api/module_table_commands_inserttablelayoutcommand-InsertTableLayoutCommand.md) – The `insertTableLayout` toolbar dropdown.

The [`TableLayout`](../../api/module_table_tablelayout-TableLayout.md) plugin registers the following UI components:

* The `'tableType'` button that allows changing the type of a selected table.
* The `'tableType'` command implemented by [`TableTypeCommand`](../../api/module_table_tablelayout_commands_tabletypecommand-TableTypeCommand.md).

You can execute the command using the [`editor.execute()`](../../api/module_core_editor_editor-Editor.md#function-execute) method. The command accepts a table type value (‘content’ or ‘layout’) as an argument.

```js
// Change the selected table to a layout table.
editor.execute('tableType', 'layout' );

// Change the selected table to a content table.
editor.execute('tableType', 'content' );
```

Additionally, if the [`TableProperties`](../../api/module_table_tableproperties-TableProperties.md) plugin is loaded, the `'tableProperties'` button will be extended with a dropdown to select the table type, providing an alternative UI for changing the table type.

> **Note**
>
> We recommend using the official [CKEditor 5 inspector](../../framework/development-tools/inspector.md) for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

<a id="contribute">

## Contribute

The source code of the feature is available on GitHub at <https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-table>.

---

Full index of the CKEditor 5 documentation: [llms.txt](../../../llms.txt)