Docs
Table

Table

Organize and display data in a structured and resizable tabular format.

Table Cell ElementTable Dropdown MenuTable ElementTable Row Element

🏓 Table

Create customizable tables with resizable columns and rows, allowing you to design structured layouts.
Plugin
Element
Inline
Void
Heading
Yes
No
No
Image
Yes
No
Yes
Mention
Yes
Yes
Yes
This table is an example of rendering a table spanning multiple columns:
Heading
Cell 1
Cell 2


Features

  • Enables creation and editing of tables with advanced behaviors.
  • Arrow navigation (up/down).
  • Grid cell selection.
  • Cell selection expansion with Shift+Arrow keys.
  • Copying and pasting cells.

Installation

npm install @udecode/plate-table

Usage

// ...
import { createTablePlugin } from '@udecode/plate-table';
 
const plugins = [
  // ...otherPlugins,
  createTablePlugin({
    options: {
      initialTableWidth: 600,
    },
  }),
];

Keyboard Interactions

KeyDescription
Shift + ArrowUp

Add the cell above to selection.

Shift + ArrowDown

Add the cell below to selection.

Shift + ArrowLeft

Add the left cell to selection.

Shift + ArrowRight

Add the right cell to selection.

Shift + TabSelect the previous cell.
TabSelect the next cell.
Cmd + ASelect all the table cells.

API

createTablePlugin

Options

Collapse all

    Disables the expansion of the table when inserting cells.

    Disables the left resizer of the first column in the table.

    Disables unsetting the width of the first column when the table has only one column. Set this to true if you want to resize the table width when there's only one column. Leave it false if you have a full-width table.

    Defines the content of a newly inserted cell.

    • Default: an empty paragraph

    The function to insert a new column into the table.

    • Default: insertTableColumn

    The function to insert a new row into the table.

    • Default: insertTableRow

    If defined, a normalizer will set each undefined table colSizes to this value divided by the number of columns. Note that merged cells are not yet supported.

    The minimum width of a column in the table.

    • Default: 48

deleteColumn

Deletes the column containing the selected cell in a table.

Parameters

Collapse all

    The editor instance.

deleteRow

Deletes the row containing the selected cell in a table.

Parameters

Collapse all

    The editor instance.

deleteTable

Deletes the entire table.

Parameters

Collapse all

    The editor instance.

getCellInNextTableRow

Gets the cell in the next row.

Parameters

Collapse all

    The editor instance.

    The path of the current row.

Returns

Collapse all

    The node entry of the cell in the next row, or undefined if the current row is the last row.

getCellInPreviousTableRow

Gets the node entry of the cell in the previous row, given the current row's path.

Parameters

Collapse all

    The editor instance.

    The path of the current row.

Returns

Collapse all

    The node entry of the cell in the previous row, or undefined if the current row is the first row.

getCellType

Get the plugin cell types.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    An array of element types for table cells (td and th) in the editor.

getEmptyCellNode

Returns an empty cell node for a table.

Parameters

Collapse all

    The editor instance.

    Extends TablePlugin.

Returns

Collapse all

    The cell node.

getEmptyRowNode

Creates an empty row node with the specified number of columns.

Parameters

Collapse all

    The editor instance.

    Extends GetEmptyCellNodeOptions.

Returns

Collapse all

    The row node.

getEmptyTableNode

Parameters

Collapse all

    The editor instance.

    Extends GetEmptyRowNodeOptions.

Returns

Collapse all

    The table node.

getLeftTableCell

Gets the cell to the left of the current cell in a table.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    The node entry of the cell to the left of the current cell, or undefined if the current cell is the first cell in the row.

getNextTableCell

Gets the next cell in the table.

Parameters

Collapse all

    The editor instance.

    The entry of the current cell.

    The path of the current cell.

    The entry of the current row.

Returns

Collapse all

    The node entry of the cell in the next row, or undefined if the current row is the last row.

getPreviousTableCell

Gets the previous cell in the table.

Parameters

Collapse all

    The editor instance.

    The entry of the current cell.

    The path of the current cell.

    The entry of the current row.

Returns

Collapse all

    The node entry of the cell in the previous row, or undefined if the current row is the first row.

getTableAbove

Gets the table node above the current selection.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    The table node entry above the current selection, or undefined if there is none.

getTableColumnCount

Gets the number of columns in a table.

Parameters

Collapse all

    The table node for which to retrieve the column count.

Returns

Collapse all

    The number of columns in the table.

getTableColumnIndex

Gets the column index of a cell node within a table.

Parameters

Collapse all

    The editor instance.

    The cell node for which to retrieve the column index.

Returns

Collapse all

    The column index of the cell node.

getTableEntries

Gets the table, row, and cell node entries based on the current selection or a specified location.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    The table node entry.

    The row node entry.

    The cell node entry.

getTableGridAbove

Gets the sub table above the anchor and focus positions based on the specified format (tables or cells).

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    The sub table entries.

getTableGridByRange

Gets the sub table between two cell paths within a given range.

Parameters

Collapse all

    The editor instance.

Returns

Collapse all

    The sub table entries.

getTableOverriddenColSizes

Gets the column sizes of a table node, with overrides applied if provided.

Parameters

Collapse all

    The table node from which to retrieve the column sizes.

    Optional overrides for the column sizes. It should be a map-like object where the keys are column indices and the values are the overridden sizes.

Returns

Collapse all

    An array of column sizes, with overrides applied if provided. If no column sizes are defined in the table node, it returns a 0-filled array.

getTableRowIndex

Gets the row index of a cell node within a table.

Parameters

Collapse all

    The editor instance.

    The cell node for which to retrieve the row index.

Returns

Collapse all

    The row index of the cell node.

getTopTableCell

Gets the cell above the current cell in the table.

Parameters

Collapse all

    The editor instance.

    The path to the current cell. If not provided, the function will search for the current cell in the editor.

Returns

Collapse all

    The cell node entry.

insertTable

Inserts a table at the current selection if there is no existing table in the editor. Selects the start of the inserted table.

Parameters

Collapse all

    The editor instance.

    Extends GetEmptyRowNodeOptions.

    The options for inserting the table nodes.

insertTableColumn

Inserts a column into the table at the current selection or a specified cell path.

Parameters

Collapse all

    The editor instance.

insertTableRow

Inserts a row into the table at the current selection or a specified row path.

Parameters

Collapse all

    The editor instance.

isTableBorderHidden

Checks if the border of a table cell or the table itself is hidden based on the specified border direction.

Parameters

Collapse all

    The editor instance.

    The border direction to check.

Returns

Collapse all

    true if the border is hidden, false otherwise.

moveSelectionFromCell

Moves the selection by cell unit within a table.

Parameters

Collapse all

    The editor instance.

overrideSelectionFromCell

Overrides the new selection if the previous selection and the new one are in different cells.

Parameters

Collapse all

    The editor instance.

    The new selection to be checked and overridden.

setBorderSize

Sets the size of the specified border in a table cell.

Parameters

Collapse all

    The editor instance.

    The size of the border.

setTableColSize

Sets the width of a specific column in a table.

Parameters

Collapse all

    The editor instance.

    Additional options for finding the table node.

setTableMarginLeft

Sets the margin left of a table.

Parameters

Collapse all

    The editor instance.

    Additional options for finding the table node.

setTableRowSize

Sets the size (height) of a table row.

Parameters

Collapse all

    The editor instance.

    Additional options for finding the table node.

API Plugin

onKeyDownTable

Handles the keyboard events for tables.

Parameters

Collapse all

    The editor instance.

    The plate plugin.

Returns

Collapse all

    The keyboard handler return type.

withDeleteTable

Prevents the deletion of cells in tables.

Parameters

Collapse all

    The editor instance.

withGetFragmentTable

If the selection is inside a table, it retrieves the subtable above the selection as the fragment. This is useful when copying and pasting table cells.

Parameters

Collapse all

    The editor instance.

withInsertFragmentTable

If inserting a table:

  • If the block above the anchor of the selection is a table, replace each cell above with the inserted table until out of bounds. Select the inserted cells.
  • If there is no table above the anchor, check if the selection is inside a table. If it is, find the cell at the anchor position and replace its children with the inserted fragment.

Parameters

Collapse all

    The editor instance.

    The plate plugin.

withInsertTextTable

If the selection is expanded:

  • Check if the selection is inside a table. If it is, collapse the selection to the focus edge.

Parameters

Collapse all

    The editor instance.

    The plate plugin.

withNormalizeTable

Normalize table structure by performing the following actions:

  • Wrap cell children in a paragraph if they are texts.
  • Unwrap nodes that are not valid table elements.
  • Set initial column sizes for tables if specified.

Parameters

Collapse all

    The editor instance.

withSelectionTable

Handle table selections by performing the following actions:

  • Adjust the focus of the selection when the anchor is inside a table and the focus is in a block before or after the table.
  • Adjust the focus of the selection when the focus is inside a table and the anchor is in a block before or after the table.
  • Override the selection from a cell if the previous and new selections are in different cells.

Parameters

Collapse all

    The editor instance.

withSetFragmentDataTable

Handle setting data to the clipboard when copying or cutting table data by performing the following actions:

  • Check if a table entry and selected cell entries exist.
  • Handle single-cell copy or cut operations by copying the cell content instead of the table structure.
  • Create a table structure with the selected cells' content.
  • Set the text, HTML, CSV, TSV, and Slate fragment data to the clipboard.

Parameters

Collapse all

    The editor instance.

withTable

Enhance the editor instance with table-related functionality by applying the following higher-order functions:

  • withNormalizeTable: Normalize table structure and content.
  • withDeleteTable: Prevent cell deletion within a table.
  • withGetFragmentTable: Handle getting the fragment data when copying or cutting table cells.
  • withInsertFragmentTable: Handle inserting table fragments.
  • withInsertTextTable: Handle inserting text within a table.
  • withSelectionTable: Handle adjusting the selection within a table.
  • withSetFragmentDataTable: Handle setting the fragment data when copying or cutting table data.

Parameters

Collapse all

    The editor instance.

    The plate plugin.

API Components

TableCellElementResizable

A component that represents the resizable handles for a table cell element.

Props

Collapse all

    The index of the column of the cell.

    The index of the row of the cell.

    The step size for resizing the table cell element.

    The step size for resizing the table cell element horizontally.

    • Default: step

    The step size for resizing the table cell element vertically.

    • Default: step

getOnSelectTableBorderFactory

Gets the onSelectTableBorder handler for a table cell element.

Parameters

Collapse all

    The editor instance.

    The selected cells.

getTableCellBorders

Gets the border styles for a table cell.

Parameters

Collapse all

    The table cell element.

Returns

Collapse all

    The border style for the bottom side of the cell.

    The border style for the right side of the cell.

    The border style for the left side of the cell. Only present if isFirstCell is true.

    • Only present if isFirstCell is true.

    The border style for the top side of the cell. Only present if isFirstRow is true.

    • Only present if isFirstRow is true.

roundCellSizeToStep

Rounds a cell size to the nearest step, or returns the size if the step is not set.

Parameters

Collapse all

    The cell size to be rounded.

    The step value used for rounding. If not provided, the size is returned as is.

useTableStore

The table store stores the state of the table plugin.

Attributes

Collapse all

    The column size overrides.

    The row size overrides.

    The margin left override.

    The hovered column index.

    The selected cells.

useIsCellSelected

Custom hook that checks if a table cell is selected.

Parameters

Collapse all

    The table cell element to check.

useSelectedCells

A hook that manages the selection of cells in a table.

It keeps track of the currently selected cells and updates them based on changes in editor selection.

useTableBordersDropdownMenuContentState

A state hook for the table borders dropdown menu content.

Returns

Collapse all

    An object with the following properties:

    Indicates whether the selected table cells have a bottom border.

    Indicates whether the selected table cells have a top border.

    Indicates whether the selected table cells have a left border.

    Indicates whether the selected table cells have a right border.

    Indicates whether the selected table cells have no borders.

    Indicates whether the selected table cells have outer borders (i.e., borders on all sides).

    A factory function that returns the onSelectTableBorder handler for a specific border type.

    • The onSelectTableBorder handler is responsible for setting the border style for the selected table cells.

useTableColSizes

Custom hook that returns the column sizes of a table with overrides applied. If the colCount of the table updates to 1 and the enableUnsetSingleColSize option is enabled, it unsets the colSizes node.

Parameters

Collapse all

    The table node.

    Additional options.

Returns

Collapse all

    The column sizes of the table with overrides applied.

useTableElement

A behavior hook for a table element.

Returns

Collapse all

    The props of the table element.

    The props of the table element.

TabbableEditable Voids