Table

'use client';

import React from 'react';

import { Plate } from '@udecode/plate-common/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,
    },
  }),
];

Without merging

'use client';

import React from 'react';

import { Plate } from '@udecode/plate-common/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: {
          enableMerging: false,
        },
      }),
    ],
    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.cell

Creates an empty cell node for a table.

editor.api.table.getCellChildren

Gets the children of a table cell.

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.

deleteColumn

Deletes the column containing the selected cell in a table.

deleteRow

Deletes the row containing the selected cell in a table.

deleteTable

Deletes the entire table.

getCellInNextTableRow

Gets the cell in the next row.

getCellInPreviousTableRow

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

getCellType

Get the plugin cell types.

getEmptyCellNode

Returns an empty cell node for a table.

getEmptyRowNode

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

getEmptyTableNode

getLeftTableCell

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

getNextTableCell

Gets the next cell in the table.

getPreviousTableCell

Gets the previous cell in the table.

getTableAbove

Gets the table node above the current selection.

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.

getTableOverriddenColSizes

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

getTableRowIndex

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

getTopTableCell

Gets the cell above the current cell in the table.

insertTable

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

insertTableColumn

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

insertTableRow

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

isTableBorderHidden

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

moveSelectionFromCell

Moves the selection by cell unit within a table.

overrideSelectionFromCell

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

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 Components

useTableCellElementResizableState

A state for the table resize handles.

useTableCellElementResizable

A behavior hook for the table resize handles.

getOnSelectTableBorderFactory

Gets the onSelectTableBorder handler for a table cell element.

getTableCellBorders

Gets the border styles for a table cell.

roundCellSizeToStep

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

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 behavior hook for a table element.

useTableElementState

A state hook for a table element.

useTableCellElement

A behavior hook for a table cell element.

useTableCellElementState

A state hook for a table cell element.