Table

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.
Row drag-and-drop reordering
Row selection via drag handle

Kit Usage

Installation

The fastest way to add table functionality is with the TableKit, which includes pre-configured TablePlugin, TableRowPlugin, TableCellPlugin, and TableCellHeaderPlugin with their Plate UI components.

TableElement: Renders table containers.
TableRowElement: Renders table rows.
TableCellElement: Renders table cells.
TableCellHeaderElement: Renders table header cells.

Add Kit

Add the kit to your plugins:

import { createPlateEditor } from 'platejs/react';
import { TableKit } from '@/components/editor/plugins/table-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    ...TableKit,
  ],
});

Manual Usage

Installation


pnpm add @platejs/table

Add Plugin

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

import { TablePlugin } from '@platejs/table/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    TablePlugin,
  ],
});

Configure Plugins

Configure the table plugins with custom components and options.

import {
  TableCellHeaderPlugin,
  TableCellPlugin,
  TablePlugin,
  TableRowPlugin,
} from '@platejs/table/react';
import { createPlateEditor } from 'platejs/react';
import {
  TableCellElement,
  TableCellHeaderElement,
  TableElement,
  TableRowElement,
} from '@/components/ui/table-node';
 
const editor = createPlateEditor({
  plugins: [
    // ...otherPlugins,
    TablePlugin.configure({
      node: { component: TableElement },
      options: {
        initialTableWidth: 600,
        disableMerge: false,
        minColumnWidth: 48,
      },
    }),
    TableRowPlugin.withComponent(TableRowElement),
    TableCellPlugin.withComponent(TableCellElement),
    TableCellHeaderPlugin.withComponent(TableCellHeaderElement),
  ],
});

node.component: Assigns TableElement to render table containers.
withComponent: Assigns components for table rows, cells, and header cells.
options.initialTableWidth: Sets the initial width for new tables.
options.disableMerge: Disables cell merging functionality.
options.minColumnWidth: Sets the minimum width for table columns.

You can add TableToolbarButton to your Toolbar to insert tables.

You can add this item to the Insert Toolbar Button to insert table elements:

{
  icon: <TableIcon />,
  label: 'Table',
  value: KEYS.table,
}

Disable Merging Example

Plugins

TablePlugin

Options

disableMerge optional boolean
Disables the merging behavior of cells.
disableExpandOnInsert optional boolean
Disables the expansion of the table when inserting cells.
disableMarginLeft optional boolean
Disables the left resizer of the first column in the table.
enableUnsetSingleColSize optional boolean
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.
initialTableWidth optional number
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.
minColumnWidth optional number
The minimum width of a column in the table.
- Default: 48

TableRowPlugin

Plugin for table rows.

TableCellPlugin

Plugin for table cells.

TableCellHeaderPlugin

Plugin for table header cells.

API

editor.api.create.table

Parameters

Collapse all

options optional GetEmptyTableNodeOptions

Extends GetEmptyRowNodeOptions.

Options

Collapse all

header optional boolean

Specify true if the table has a header row.

rowCount optional number

The number of rows in the table.

Default: 0

colCount optional number | undefined

The number of columns in the table.

Returns

Collapse all

TElement

The table node.

editor.api.create.tableCell

Creates an empty cell node for a table.

Options

Collapse all

header optional boolean

Specify true if the cell is a header cell.

row optional TTableRowElement

The row element. If header is not specified, it will determine if the cell is a header cell based on the row's children.

children optional Descendant[]

The children of the new cell node.

Default: [editor.api.create.block()]

Returns

Collapse all

TElement

The cell node.

editor.api.create.tableRow

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

Options

Collapse all

header optional boolean

Specify true if the row is a header row.

colCount optional number

The number of columns in the row.

Default: 1

Returns

Collapse all

TElement

The row node.

editor.api.table.getCellBorders

Gets the border styles for a table cell, handling special cases for first row and first column cells.

Options

Collapse all

element TTableCellElement

The table cell element to get the border styles for.

defaultBorder optional Required<TTableCellElementBorder>

The default border style to use when cell borders are not defined.

Returns

Collapse all

BorderStylesDefault

An object containing:

editor.api.table.getCellChildren

Gets the children of a table cell.

Parameters

Collapse all

cell TElement

The table cell element.

Returns

Collapse all

Descendant[]

The children of the table cell.

editor.api.table.getCellSize

Gets the width and minimum height of a table cell, taking into account column spans and column sizes.

Options

Collapse all

element TTableCellElement

The table cell element to get the size for.

colSizes optional number[]

Optional array of column sizes. If not provided, will use the table's overridden column sizes.

Returns

Collapse all

width number

The total width of the cell, calculated by summing the widths of all columns it spans.

minHeight number | undefined

The minimum height of the cell, derived from the row's size property.

editor.api.table.getColSpan

Gets the column span of a table cell.

Parameters

Collapse all

element TTableCellElement

The table cell element to get the column span for.

Returns

Collapse all

number

The number of columns this cell spans.

Default: 1

editor.api.table.getRowSpan

Gets the row span of a table cell.

Parameters

Collapse all

element TTableCellElement

The table cell element to get the row span for.

Returns

Collapse all

number

The number of rows this cell spans.

Default: 1

getCellType

Get the plugin cell types.

Returns

Collapse all

string[]

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

getNextTableCell

Gets the next cell in the table.

Parameters

Collapse all

currentCell NodeEntry

The entry of the current cell.

currentPath Path

The path of the current cell.

currentRow NodeEntry

The entry of the current row.

Returns

Collapse all

NodeEntry | undefined

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

currentCell NodeEntry

The entry of the current cell.

currentPath Path

The path of the current cell.

currentRow NodeEntry

The entry of the current row.

Returns

Collapse all

NodeEntry | undefined

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

getTableColumnCount

Gets the number of columns in a table.

Parameters

Collapse all

tableNode TElement

The table node for which to retrieve the column count.

Returns

Collapse all

number

The number of columns in the table.

getTableColumnIndex

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

Parameters

Collapse all

cellNode TElement

The cell node for which to retrieve the column index.

Returns

Collapse all

number

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.

Options

Collapse all

at optional Location | null

The location where the table cell is located.

Default: editor.selection

Returns

Collapse all

table NodeEntry | undefined

The table node entry.

row NodeEntry | undefined

The row node entry.

cell NodeEntry | undefined

The cell node entry.

getTableGridAbove

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

Options

Collapse all

format optional string

The format of the sub table to retrieve.

Default: 'table'

Returns

Collapse all

ElementEntry[]

The sub table entries.

getTableGridByRange

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

Options

Collapse all

at TRange

The range specifying the start and end cell paths.

format optional 'table' | 'cell'

The format of the output.

Default: 'table'

Returns

Collapse all

ElementEntry[]

The sub table entries.

getTableRowIndex

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

Parameters

Collapse all

cellNode TElement

The cell node for which to retrieve the row index.

Returns

Collapse all

number

The row index of the cell node.

getTopTableCell

Gets the cell above the current cell in the table.

Parameters

Collapse all

at optional Path

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

Returns

Collapse all

ElementEntry | undefined

The cell node entry.

isTableBorderHidden

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

Parameters

Collapse all

border 'top' | 'left' | 'bottom' | 'right'

The border direction to check.

Returns

Collapse all

boolean

true if the border is hidden, false otherwise.

Transforms

`tf.insert.table`

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

getEmptyTableNodeOptions optional GetEmptyTableNodeOptions

Extends GetEmptyRowNodeOptions.

options optional InsertNodesOptions

The options for inserting the table nodes.

`tf.insert.tableColumn`

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

Options

Collapse all

at optional Path

The exact path of the cell to insert the column at. This overrules the fromCell option.

before optional boolean

If true, insert the column before the current column instead of after.

fromCell optional Path

The path of the cell to insert the column from.

header optional boolean

If true, the inserted column will be treated as a header column.

select optional boolean

If true, the inserted column will be selected after insertion.

`tf.insert.tableRow`

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

Options

Collapse all

at optional Path

Exact path of the row to insert the column at. Pass the table path to insert at the end of the table. Will overrule fromRow.

before optional boolean

If true, insert the row before the current row instead of after.

fromRow optional Path

The path of the row to insert the new row from.

header optional boolean

If true, the inserted row will be treated as a header row.

select optional boolean

If true, the inserted row will be selected after insertion.

`tf.remove.tableColumn`

Deletes the column containing the selected cell in a table.

`tf.remove.tableRow`

Deletes the row containing the selected cell in a table.

`tf.remove.table`

Deletes the entire table.

`tf.table.merge`

Merges multiple selected cells into one.

The merged cell will:

Have a colSpan equal to the number of columns spanned by the selected cells
Have a rowSpan equal to the number of rows spanned by the selected cells
Contain the combined content of all merged cells (non-empty cells only)
Inherit the header status from the first selected cell

`tf.table.split`

Splits a merged cell back into individual cells.

The split operation will:

Create new cells for each column and row that was spanned
Copy the header status from the original merged cell
Place the original cell's content in the first cell
Create empty cells for the remaining spaces

`tf.moveSelectionFromCell`

Moves the selection by cell unit within a table.

Options

Collapse all

at optional Location

The location to move the selection from.

reverse optional boolean

Set to true to move the selection to the cell above, false to move the selection to the cell below.

edge optional 'top' | 'left' | 'right' | 'bottom'

The edge to expand the cell selection to.

fromOneCell optional boolean

Set to true to move the selection from only one selected cell.

`tf.setBorderSize`

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

Parameters

Collapse all

size number

The size of the border.

options optional object

Options for setting the border size.

Options

Collapse all

at optional Location

The location of the cell to set the border size.

border optional 'all' | 'top' | 'left' | 'bottom' | 'right'

The border direction to set the size.

Default: 'all'

`tf.setTableColSize`

Sets the width of a specific column in a table.

Options

Collapse all

colIndex optional number

The index of the column to set the width.

width optional number

The desired width of the column.

getAboveNodeOptions optional EditorAboveOptions

Additional options for finding the table node.

`tf.setTableMarginLeft`

Sets the margin left of a table.

Options

Collapse all

marginLeft number

An object containing the desired margin left value.

getAboveNodeOptions optional EditorAboveOptions

Additional options for finding the table node.

`tf.setTableRowSize`

Sets the size (height) of a table row.

Options

Collapse all

rowIndex number

The index of the row to set the size.

height number

The desired height of the row.

getAboveNodeOptions optional EditorAboveOptions

Additional options for finding the table node.

Plugin Extensions

`onKeyDownTable`

Handles the keyboard events for tables.

Parameters

Collapse all

plugin PlatePlugin

The plate plugin.

Returns

Collapse all

KeyboardHandlerReturnType

The keyboard handler return type.

`withDeleteTable`

Prevents the deletion of cells in tables.

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

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

`withInsertTextTable`

If the selection is expanded:

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

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

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

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

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

Hooks

`useTableCellElementResizable`

A hook that provides resizing functionality for table cell elements.

OptionsTableCellElementResizableOptions

Collapse all

colIndex number

The index of the column.

colSpan number

The number of columns this cell spans.

rowIndex number

The index of the row.

step optional number

Resize by step instead of by pixel.

stepX optional number

Step size for horizontal resizing.

stepY optional number

Step size for vertical resizing.

Default: step

Returns

Collapse all

bottomProps ResizeHandleProps

Props for the bottom resize handle, including resize direction and handler.

hiddenLeft boolean

Whether the left resize handle should be hidden. True if not the first column or margin left is disabled.

leftProps ResizeHandleProps

Props for the left resize handle, including resize direction and handler.

rightProps ResizeHandleProps

Props for the right resize handle, including resize direction, initial size, and handler.

`useTableStore`

The table store stores the state of the table plugin.

Attributes

Collapse all

colSizeOverrides TableStoreSizeOverrides

The column size overrides.

rowSizeOverrides TableStoreSizeOverrides

The row size overrides.

marginLeftOverride number | null

The margin left override.

selectedCells TElement[] | null

The selected cells.

selectedTables TElement[] | null

The selected tables.

`useIsCellSelected`

Custom hook that checks if a table cell is selected.

Parameters

Collapse all

element TElement

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:

hasBottomBorder boolean

Indicates whether the selected table cells have a bottom border.

hasTopBorder boolean

Indicates whether the selected table cells have a top border.

hasLeftBorder boolean

Indicates whether the selected table cells have a left border.

hasRightBorder boolean

Indicates whether the selected table cells have a right border.

hasNoBorders boolean

Indicates whether the selected table cells have no borders.

hasOuterBorders boolean

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

getOnSelectTableBorder function

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.

Options

Collapse all

disableOverrides optional boolean

If true, disables applying overrides to the column sizes.

Default: false

Returns

Collapse all

overriddenColSizes number[]

The column sizes of the table with overrides applied.

`useTableElement`

A hook for a table element that handles cell selection and margin left calculations.

Returns

Collapse all

isSelectingCell boolean

Whether cells are currently being selected.

marginLeft number

The margin left of the table, considering overrides and plugin options.

props object

Props for the table element:

`useTableCellElement`

A hook for a table cell element that provides state and functionality for table cells.

Returns

Collapse all

borders BorderStylesDefault

The border styles of the table cell.

colIndex number

The ending column index (considering colSpan).

colSpan number

The number of columns this cell spans.

isSelectingCell boolean

Whether cells are currently being selected.

minHeight number | undefined

The minimum height of the cell.

rowIndex number

The ending row index (considering rowSpan).

selected boolean

Whether this cell is currently selected.

width number | string

The width of the cell.

`useTableCellBorders`

A hook that returns the border styles for a table cell.

Returns

Collapse all

BorderStylesDefault

An object containing the border styles for the cell:

`useTableCellSize`

A hook that returns the size (width and minimum height) of a table cell.

Returns

Collapse all

object

An object containing:

表格目录

On This Page

Features Kit Usage Installation Add Kit Manual Usage Installation Add Plugin Configure Plugins Add Toolbar Button Insert Toolbar Button Disable Merging Example Plugins TablePlugin TableRowPlugin TableCellPlugin TableCellHeaderPlugin API editor.api.create.table editor.api.create.tableCell editor.api.create.tableRow editor.api.table.getCellBorders editor.api.table.getCellChildren editor.api.table.getCellSize editor.api.table.getColSpan editor.api.table.getRowSpan getCellType getNextTableCell getPreviousTableCell getTableColumnCount getTableColumnIndex getTableEntries getTableGridAbove getTableGridByRange getTableRowIndex getTopTableCell isTableBorderHidden Transforms tf.insert.tabletf.insert.tableColumntf.insert.tableRowtf.remove.tableColumntf.remove.tableRowtf.remove.tabletf.table.mergetf.table.splittf.moveSelectionFromCelltf.setBorderSizetf.setTableColSizetf.setTableMarginLefttf.setTableRowSizePlugin Extensions onKeyDownTablewithDeleteTablewithGetFragmentTablewithInsertFragmentTablewithInsertTextTablewithNormalizeTablewithSelectionTablewithSetFragmentDataTablewithTableHooks useTableCellElementResizableuseTableStoreuseIsCellSelecteduseSelectedCellsuseTableBordersDropdownMenuContentStateuseTableColSizesuseTableElementuseTableCellElementuseTableCellBordersuseTableCellSize

Table

Features

Kit Usage

Installation

Add Kit

Manual Usage

Installation

Add Plugin

Configure Plugins

Add Toolbar Button

Insert Toolbar Button

Disable Merging Example

Plugins

TablePlugin

Options

disableMerge optional boolean

disableExpandOnInsert optional boolean

disableMarginLeft optional boolean

enableUnsetSingleColSize optional boolean

initialTableWidth optional number

minColumnWidth optional number

TableRowPlugin

TableCellPlugin

TableCellHeaderPlugin

API

editor.api.create.table

Parameters

options optional GetEmptyTableNodeOptions

Options

header optional boolean

rowCount optional number

colCount optional number | undefined

Returns

TElement

editor.api.create.tableCell

Options

header optional boolean

row optional TTableRowElement

children optional Descendant[]

Returns

TElement

editor.api.create.tableRow

Options

header optional boolean

colCount optional number

Returns

TElement

editor.api.table.getCellBorders

Options

element TTableCellElement

defaultBorder optional Required<TTableCellElementBorder>

Show child attributes

Returns

BorderStylesDefault

Show child attributes

editor.api.table.getCellChildren

Parameters

cell TElement

Returns

Descendant[]

editor.api.table.getCellSize

Options

element TTableCellElement

colSizes optional number[]

Returns

width number

minHeight number | undefined

editor.api.table.getColSpan

Parameters

element TTableCellElement

Returns

number

editor.api.table.getRowSpan

Parameters

element TTableCellElement

Returns

number

getCellType

Returns

string[]

`tf.insert.table`