Table and cell styling tools

CKEditor 5 comes with some additional tools that help you modify the look of tables and table cells. You can control border color and style, background color, padding, or text alignment.

# Demo

Put the caret anywhere inside the table to open the table toolbar. Click the table properties button in the toolbar. A pop–up will open with options to shape the look of the entire table. On the other hand, the cell properties button gives you access to styling options for individual table cells.

Learn more about configuring color palettes in the table styling pop–up interfaces.

# Installation

To enable the rich table and cell styling tools in your editor, you need to have the @ckeditor/ckeditor5-table package installed (it is already present in the predefined builds):

npm install --save @ckeditor/ckeditor5-table

Then add the Table, TableToolbar, TableProperties, and TableCellProperties plugins to your plugin list and configure the table toolbar:

import Table from '@ckeditor/ckeditor5-table/src/table';
import TableToolbar from '@ckeditor/ckeditor5-table/src/tabletoolbar';
import TableProperties from '@ckeditor/ckeditor5-table/src/tableproperties';
import TableCellProperties from '@ckeditor/ckeditor5-table/src/tablecellproperties';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Table, TableToolbar, TableProperties, TableCellProperties, Bold, /* ... */ ],
        toolbar: [ 'insertTable', /* ... */ ],
        table: {
            contentToolbar: [
                'tableColumn', 'tableRow', 'mergeTableCells',
                'tableProperties', 'tableCellProperties'
            ],

            tableProperties: {
                // Configuration of the TableProperties plugin.
                // ...
            },

            tableCellProperties: {
                // Configuration of the TableCellProperties plugin.
                // ...
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Configuring styling tools

Table and cell styling tools let you create tables with colorful backgrounds and borders. These colors can be easily picked using color palettes in the table properties and cell properties pop-ups. To help users choose the right colors for the content, you can pre-configure such color palettes, like in the editor below:

With the selection inside any table cell, use the table properties and cell properties buttons in the toolbar to check available styling and color options.

# Customizing color palettes

You can use these specific configuration options to define customized color palettes for background and border colors to match your document:

• tableProperties.borderColors – Defines the color palette for table borders.
• tableProperties.backgroundColors – Defines the color palette for table background.
• tableCellProperties.borderColors – Defines the color palette for cell borders.
• tableCellProperties.backgroundColors – Defines the color palette for cell background.

For instance, to define the same color palette for all border and background configurations, use the following code snippet:

const customColorPalette = [
    {
        color: 'hsl(4, 90%, 58%)',
        label: 'Red'
    },
    {
        color: 'hsl(340, 82%, 52%)',
        label: 'Pink'
    },
    {
        color: 'hsl(291, 64%, 42%)',
        label: 'Purple'
    },
    {
        color: 'hsl(262, 52%, 47%)',
        label: 'Deep Purple'
    },
    {
        color: 'hsl(231, 48%, 48%)',
        label: 'Indigo'
    },
    {
        color: 'hsl(207, 90%, 54%)',
        label: 'Blue'
    },

    // More colors.
    // ...
];

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Table, TableToolbar, TableProperties, TableCellProperties, Bold, /* ... */ ],
        toolbar: [ 'insertTable', /* ... */ ],
        table: {
            contentToolbar: [
                'tableColumn', 'tableRow', 'mergeTableCells',
                'tableProperties', 'tableCellProperties'
            ],

            // Set the palettes for tables.
            tableProperties: {
                borderColors: customColorPalette,
                backgroundColors: customColorPalette
            },

            // Set the palettes for table cells.
            tableCellProperties: {
                borderColors: customColorPalette,
                backgroundColors: customColorPalette
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# Default table and table cell styles

The table styles feature allows for configuring the default look of the tables in the editor. The configuration object should be synchronized with the editor content styles.

The “Table properties” and “Table cell properties” buttons in the toolbar will show the table and table cell properties applied to the table or table cells.

The stylesheet for the editor displayed below looks as follows:

.ck-content .table {
    float: left;
    width: 550px;
    height: 450px;
}

.ck-content .table table {
    border-style: dashed;
    border-color: 'hsl(90, 75%, 60%)';
    border-width: 3px;
}

.ck-content .table table td {
    text-align: center;
    vertical-align: bottom;
    padding: 10px
}

The same values must be passed to the editor configuration as:

• The table.tableProperties.defaultProperties object for the table properties.
• The table.tableCellProperties.defaultProperties object for the table cell properties.

const tableConfig = {
    table: {
        tableProperties: {
            // The default styles for tables in the editor.
            // They should be synchronized with the content styles.
            defaultProperties: {
                borderStyle: 'dashed',
                borderColor: 'hsl(90, 75%, 60%)',
                borderWidth: '3px',
                alignment: 'left',
                width: '550px',
                height: '450px'
            },
            // The default styles for table cells in the editor.
            // They should be synchronized with the content styles.
            tableCellProperties: {
                defaultProperties: {
                    horizontalAlignment: 'center',
                    verticalAlignment: 'bottom',
                    padding: '10px'
                }
            }
        }
    }
};

The table element should be aligned to the left side by default. Its size should be 550x450px. The border style should be dashed, 3px of its width, and the color specified as Light green.

The content should be away about 10px from the cell’s edges (padding), vertically aligned to bottom and horizontally to center.

The same will be applied to new tables and cells if they are inserted into the editor.

Read more about all supported properties for the table and table cell features in their API documentation.

# Common API

# UI components

The TableProperties and TableCellProperties plugins register the following UI components:

Component name	Registered by
The 'tableProperties' button	TableProperties
The 'tableCellProperties' button	TableCellProperties

# Toolbars

The TableProperties and TableCellProperties plugins allow adding the tableProperties and tableCellProperties items to the toolbar. It is possible to configure its content.

# Editor commands

Command name	Command class	Belongs to (top–level plugin)
'tableBorderColor'	TableBorderColorCommand	TableProperties
'tableBorderStyle'	TableBorderStyleCommand
'tableBorderWidth'	TableBorderWidthCommand
'tableAlignment'	TableAlignmentCommand
'tableWidth'	TableWidthCommand
'tableHeight'	TableHeightCommand
'tableBackgroundColor'	TableBackgroundColorCommand
'tableCellBorderStyle'	TableCellBorderStyleCommand	TableCellProperties
'tableCellBorderColor'	TableCellBorderColorCommand
'tableCellBorderWidth'	TableCellBorderWidthCommand
'tableCellHorizontalAlignment'	TableCellHorizontalAlignmentCommand
'tableCellWidth'	TableCellWidthCommand
'tableCellHeight'	TableCellHeightCommand
'tableCellPadding'	TableCellPaddingCommand
'tableCellBackgroundColor'	TableCellBackgroundColorCommand
'tableCellVerticalAlignment'	TableCellVerticalAlignmentCommand

# Contribute

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