Table

'use client';

import React from 'react';

import { Plate } from '@udecode/plate/react';

import { editorPlugins } from '@/components/editor/plugins/editor-plugins';
import { useCreateEditor } from '@/components/editor/use-create-editor';
import { Editor, EditorContainer } from '@/components/plate-ui/editor';

import { DEMO_VALUES } from './values/demo-values';

export default function Demo({ id }: { id: string }) {
  const editor = useCreateEditor({
    plugins: [...editorPlugins],
    value: DEMO_VALUES[id],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}

Installation

npm install @udecode/plate-table

Usage

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

Disable merging

'use client';

import React from 'react';

import { Plate } from '@udecode/plate/react';
import { TablePlugin } from '@udecode/plate-table/react';

import { editorPlugins } from '@/components/editor/plugins/editor-plugins';
import { useCreateEditor } from '@/components/editor/use-create-editor';
import { tableValue } from '@/components/values/table-value';
import { Editor, EditorContainer } from '@/components/plate-ui/editor';

export default function TableMergeDemo() {
  const editor = useCreateEditor({
    plugins: [
      ...editorPlugins,
      TablePlugin.configure({
        options: {
          disableMerge: true,
        },
      }),
    ],
    value: tableValue,
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}

Plugins

TablePlugin

TableRowPlugin

Plugin for table rows.

TableCellPlugin

Plugin for table cells.

TableCellHeaderPlugin

Plugin for table header cells.

API

editor.api.create.table

editor.api.create.tableCell

Creates an empty cell node for a table.

editor.api.create.tableRow

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

editor.api.table.getCellBorders

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

editor.api.table.getCellChildren

Gets the children of a table cell.

editor.api.table.getCellSize

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

editor.api.table.getColSpan

Gets the column span of a table cell.

editor.api.table.getRowSpan

Gets the row span of a table cell.

getCellType

Get the plugin cell types.

getNextTableCell

Gets the next cell in the table.

getPreviousTableCell

Gets the previous cell in the table.

getTableColumnCount

Gets the number of columns in a table.

getTableColumnIndex

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

getTableEntries

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

getTableGridAbove

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

getTableGridByRange

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

getTableRowIndex

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

getTopTableCell

Gets the cell above the current cell in the table.

isTableBorderHidden

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

API Transforms

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

editor.tf.insert.tableColumn

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

editor.tf.insert.tableRow

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

editor.tf.remove.tableColumn

Deletes the column containing the selected cell in a table.

editor.tf.remove.tableRow

Deletes the row containing the selected cell in a table.

editor.tf.remove.table

Deletes the entire table.

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

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

moveSelectionFromCell

Moves the selection by cell unit within a table.

setBorderSize

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

setTableColSize

Sets the width of a specific column in a table.

setTableMarginLeft

Sets the margin left of a table.

setTableRowSize

Sets the size (height) of a table row.

API Plugin

onKeyDownTable

Handles the keyboard events for tables.

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.

API Hooks

useTableCellElementResizable

A hook that provides resizing functionality for table cell elements.

useTableStore

The table store stores the state of the table plugin.

useIsCellSelected

Custom hook that checks if a table cell is selected.

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.

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.

useTableElement

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

useTableCellElement

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

useTableCellBorders

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

useTableCellSize

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