Layout tables

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 and layout tables by using the table toggling feature.

# Table types comparison

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

• Regular content tables – Content tables provide the basic table experience for presentation of tabular data.
• Table layout – 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 – This plugin strips the <figure> tag from the table data. It is basically an email client compatibility feature.

# 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.

# 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 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 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.

# Installation

After installing the editor, add the feature to your plugin list and toolbar configuration:

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

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

# Configuration

# 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 option to content or layout.

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

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

# Configuring the table toggle feature

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

1. Include the TableLayout 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 and TableToolbar 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.

# Configuring table toggle with TableProperties

When the TableProperties plugin is available, table type options will be integrated into the table properties dropdown:

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

ClassicEditor
	.create( document.querySelector( '#editor' ), {
		licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
		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:

# 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:

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

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

# 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.

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

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

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

# Related features

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

• Email editing – The email editing solution is a set of tools aimed at making the email composition a better and more effective experience.
• Email configuration helper – The email configuration helper plugin is the best way to start writing and editing emails.

# Common API

The TableLayout plugin registers the following command:

• TableLayoutEditing – The layout table editing command.
• TableLayoutUI – The layout table UI.
• InsertTableLayoutCommand – The insertTableLayout toolbar dropdown.

The TableLayout plugin registers the following UI components:

• The 'tableType' button that allows changing the type of a selected table.
• The 'tableType' command implemented by TableTypeCommand.

You can execute the command using the editor.execute() method. The command accepts a table type value (‘content’ or ‘layout’) as an argument.

// 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 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.

# Contribute

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