Table
Organize and display data in a structured and resizable tabular format.
🏓 Table
Plugin | Element | Inline | Void |
|---|---|---|---|
Heading | | | No |
Image | Yes | No | Yes |
Mention | Yes | Yes | Yes |
Table Merge
enableMerging: true option. Try it out:Plugin | |||
|---|---|---|---|
Heading | | | No |
Image | Yes | No | Yes |
Mention | Yes | Yes | Yes |
Installation
npm install @udecode/plate-tableUsage
// ...
import { createTablePlugin } from '@udecode/plate-table';
const plugins = [
// ...otherPlugins,
createTablePlugin({
options: {
initialTableWidth: 600,
},
}),
];Keyboard Interactions
| Key | Description |
|---|---|
| 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 + Tab | Select the previous cell. |
| Tab | Select the next cell. |
| Cmd + A | Select all the table cells. |
API
createTablePlugin
Options
- Default: an empty paragraph
- Default:
insertTableColumn - Default:
insertTableRow - Default:
48
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.
The function to insert a new column into the table.
The function to insert a new row into the table.
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.
deleteColumn
Deletes the column containing the selected cell in a table.
Parameters
The editor instance.
deleteRow
Deletes the row containing the selected cell in a table.
Parameters
The editor instance.
deleteTable
Deletes the entire table.
Parameters
The editor instance.
getCellInNextTableRow
Gets the cell in the next row.
Parameters
The editor instance.
The path of the current row.
Returns
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
The editor instance.
The path of the current row.
Returns
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
The editor instance.
Returns
An array of element types for table cells (td and th) in the editor.
getEmptyCellNode
Returns an empty cell node for a table.
Parameters
The editor instance.
Extends TablePlugin.
Returns
The cell node.
getEmptyRowNode
Creates an empty row node with the specified number of columns.
Parameters
The editor instance.
Extends GetEmptyCellNodeOptions.
Returns
The row node.
getEmptyTableNode
Parameters
The editor instance.
Extends GetEmptyRowNodeOptions.
Returns
The table node.
getLeftTableCell
Gets the cell to the left of the current cell in a table.
Parameters
The editor instance.
Returns
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
The editor instance.
The entry of the current cell.
The path of the current cell.
The entry of the current row.
Returns
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
The editor instance.
The entry of the current cell.
The path of the current cell.
The entry of the current row.
Returns
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
The editor instance.
Returns
The table node entry above the current selection, or undefined if there is
none.
getTableColumnCount
Gets the number of columns in a table.
Parameters
The table node for which to retrieve the column count.
Returns
The number of columns in the table.
getTableColumnIndex
Gets the column index of a cell node within a table.
Parameters
The editor instance.
The cell node for which to retrieve the column index.
Returns
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
The editor instance.
Returns
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
The editor instance.
Returns
getTableGridByRange
Gets the sub table between two cell paths within a given range.
Parameters
The editor instance.
Returns
getTableOverriddenColSizes
Gets the column sizes of a table node, with overrides applied if provided.
Parameters
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
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
The editor instance.
The cell node for which to retrieve the row index.
Returns
The row index of the cell node.
getTopTableCell
Gets the cell above the current cell in the table.
Parameters
The editor instance.
The path to the current cell. If not provided, the function will search for the current cell in the editor.
Returns
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
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
The editor instance.
insertTableRow
Inserts a row into the table at the current selection or a specified row path.
Parameters
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
The editor instance.
The border direction to check.
Returns
true if the border is hidden, false otherwise.
moveSelectionFromCell
Moves the selection by cell unit within a table.
Parameters
The editor instance.
overrideSelectionFromCell
Overrides the new selection if the previous selection and the new one are in different cells.
Parameters
The editor instance.
The new selection to be checked and overridden.
setBorderSize
Sets the size of the specified border in a table cell.
Parameters
The editor instance.
The size of the border.
setTableColSize
Sets the width of a specific column in a table.
Parameters
The editor instance.
Additional options for finding the table node.
setTableMarginLeft
Sets the margin left of a table.
Parameters
The editor instance.
Additional options for finding the table node.
setTableRowSize
Sets the size (height) of a table row.
Parameters
The editor instance.
Additional options for finding the table node.
API Plugin
onKeyDownTable
Handles the keyboard events for tables.
Parameters
The editor instance.
The plate plugin.
Returns
The keyboard handler return type.
withDeleteTable
Prevents the deletion of cells in tables.
Parameters
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
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
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
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
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
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
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
The editor instance.
The plate plugin.
API Components
useTableCellElementResizableState
A state for the table resize handles.
Options
- Default:
step - Default:
step
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.
The step size for resizing the table cell element vertically.
Returns
Whether to disable the margin left.
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 horizontally.
The step size for resizing the table cell element vertically.
useTableCellElementResizable
A behavior hook for the table resize handles.
Parameters
The state returned by useTableCellElementResizableState.
Returns
The props for the right resize handle.
The props for the bottom resize handle.
The props for the left resize handle.
Whether the left resize handle is hidden.
getOnSelectTableBorderFactory
Gets the onSelectTableBorder handler for a table cell element.
Parameters
The editor instance.
The selected cells.
getTableCellBorders
Gets the border styles for a table cell.
Parameters
The table cell element.
Returns
- Only present if
isFirstCellistrue. - Only present if
isFirstRowistrue.
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.
The border style for the top side of the cell. 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
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
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
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
- The
onSelectTableBorderhandler is responsible for setting the border style for the selected table cells.
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.
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
The table node.
Additional options.
Returns
The column sizes of the table with overrides applied.
useTableElement
A behavior hook for a table element.
Returns
The props of the table element.
The props of the table element.
useTableElementState
A state hook for a table element.
Parameters
Returns
The column sizes of the table.
Indicates whether the user is currently selecting cells.
The minimum column width.
The margin left of the table.
useTableCellElement
A behavior hook for a table cell element.
Parameters
Returns
The props of the table cell element.
useTableCellElementState
A state hook for a table cell element.
Parameters
Returns
The column index of the table cell.
The row index of the table cell.
Indicates whether the table cell is read only.
Indicates whether the table cell is selected.
Indicates whether the table cell is hovered.
Indicates whether the table cell is hovered left.
The row size of the table cell.
The border styles of the table cell.
Indicates whether the user is currently selecting cells.