Table

Loading...
Files
components/demo.tsx
'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>
  );
}

Features

  • Table editing with support for:
    • Adding/removing rows and columns
    • Merging/splitting cells
    • Cell resizing
    • Cell borders
    • Header rows/columns
    • Copy/paste table data
    • Keyboard navigation

Installation

npm install @udecode/plate-table

Usage

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

API

editor.api.create.table

Parameters

Collapse all

    The editor instance.

    Options for creating the table.

OptionsGetEmptyTableNodeOptions

Collapse all

    Specify true if the table has a header row.

    The number of rows in the table.

    • Default: 0

    The number of columns in the table.

ReturnsTElement

    The table node.

editor.api.create.tableCell

Creates an empty cell node for a table.

OptionsCreateCellOptions

Collapse all

    Specify true if the cell is a header cell.

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

    The children of the new cell node.

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

ReturnsTElement

    The cell node.

editor.api.create.tableRow

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

Parameters

Collapse all

    The editor instance.

    Options for creating the row.

OptionsGetEmptyRowNodeOptions

Collapse all

    Specify true if the row is a header row.

    The number of columns in the row.

    • Default: 1

ReturnsTElement

    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.

Parameters

Collapse all

    The editor instance.

    Options for getting cell borders.

Options

Collapse all

    The table cell element to get the border styles for.

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

ReturnsBorderStylesDefault

Collapse all

    The bottom border style.

    The right border style.

    The left border style. Only present for cells in the first column.

    The top border style. Only present for cells in the first row.

editor.api.table.getCellChildren

Parameters

Collapse all

    The table cell element.

ReturnsDescendant[]

    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.

Parameters

Collapse all

    The editor instance.

    Options for getting cell size.

Options

Collapse all

    The table cell element to get the size for.

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

Returnsobject

Collapse all

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

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

editor.api.table.getColSpan

Parameters

Collapse all

    The table cell element to get the column span for.

Returnsnumber

    The number of columns this cell spans.

    • Default: 1

editor.api.table.getRowSpan

Parameters

Collapse all

    The table cell element to get the row span for.

Returnsnumber

    The number of rows this cell spans.

    • Default: 1

getCellType

Parameters

Collapse all

    The editor instance.

Returnsstring[]

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

getNextTableCell

Parameters

Collapse all

    The editor instance.

    The entry of the current cell.

    The path of the current cell.

    The entry of the current row.

ReturnsNodeEntry | undefined

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

getPreviousTableCell

Parameters

Collapse all

    The editor instance.

    The entry of the current cell.

    The path of the current cell.

    The entry of the current row.

ReturnsNodeEntry | undefined

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

getTableColumnCount

Parameters

Collapse all

    The table node for which to retrieve the column count.

Returnsnumber

    The number of columns in the table.

getTableColumnIndex

Parameters

Collapse all

    The editor instance.

    The cell node for which to retrieve the column index.

Returnsnumber

    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.

    Options for getting table entries.

Options

Collapse all

    The location where the table cell is located.

    • Default: editor.selection

Returnsobject

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.

Parameters

Collapse all

    The editor instance.

    Options for getting the table grid above.

Options

Collapse all

    The format of the sub table to retrieve.

    • Default: 'table'

ReturnsElementEntry[]

    The sub table entries.

getTableGridByRange

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

Parameters

Collapse all

    The editor instance.

    Options for getting the table grid by range.

Options

Collapse all

    The range specifying the start and end cell paths.

    The format of the output.

    • Default: 'table'

ReturnsElementEntry[]

    The sub table entries.

getTableRowIndex

Parameters

Collapse all

    The editor instance.

    The cell node for which to retrieve the row index.

Returnsnumber

    The row index of the cell node.

getTopTableCell

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.

ReturnsElementEntry | undefined

    The cell node entry.

isTableBorderHidden

Parameters

Collapse all

    The editor instance.

    The border direction to check.

Returnsboolean

    true if the border is hidden, false otherwise.

moveSelectionFromCell

Moves the selection by cell unit within a table.

Parameters

Collapse all

    The editor instance.

    Options for moving the selection.

Options

Collapse all

    The location to move the selection from.

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

    The edge to expand the cell selection to.

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

onKeyDownTable

Parameters

Collapse all

    The editor instance.

    The plate plugin.

ReturnsKeyboardHandlerReturnType

    The keyboard handler return type.

setBorderSize

Parameters

Collapse all

    The editor instance.

    The size of the border.

    Options for setting the border size.

Options

Collapse all

    The location of the cell to set the border size.

    The border direction to set the size.

    • Default: 'all'

setTableColSize

Parameters

Collapse all

    The editor instance.

    Options for setting column size.

    Additional options for finding the table node.

Options

Collapse all

    The index of the column to set the width.

    The desired width of the column.

setTableMarginLeft

Parameters

Collapse all

    The editor instance.

    Options for setting table margin.

    Additional options for finding the table node.

Options

Collapse all

    The desired margin left value.

setTableRowSize

Parameters

Collapse all

    The editor instance.

    Options for setting row size.

    Additional options for finding the table node.

Options

Collapse all

    The index of the row to set the size.

    The desired height of the row.

TablePlugin

Options

Collapse all

    Disables the merging behavior of cells.

    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.

    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

useIsCellSelected

Parameters

Collapse all

    The table cell element to check.

Returnsboolean

    Whether the cell is currently selected.

useSelectedCells

ReturnsTElement[] | null

    The currently selected table cells. Returns null if no cells are selected.

useTableBordersDropdownMenuContentState

Returnsobject

Collapse all

    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.

useTableCellElement

Returnsobject

Collapse all

    The border styles of the table cell.

    The ending column index (considering colSpan).

    The number of columns this cell spans.

    Whether cells are currently being selected.

    The minimum height of the cell.

    The ending row index (considering rowSpan).

    Whether this cell is currently selected.

    The width of the cell.

useTableCellElementResizable

OptionsTableCellElementResizableOptions

Collapse all

    The index of the column.

    The number of columns this cell spans.

    The index of the row.

    Resize by step instead of by pixel.

    Step size for horizontal resizing.

    • Default: step

    Step size for vertical resizing.

    • Default: step

Returnsobject

Collapse all

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

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

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

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

useTableColSizes

Options

Collapse all

    If true, disables applying overrides to the column sizes.

    • Default: false

Returnsobject

Collapse all

    The column sizes of the table with overrides applied.

useTableElement

Returnsobject

Collapse all

    Whether cells are currently being selected.

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

    Props for the table element:

useTableStore

State

Collapse all

    The column size overrides.

    The row size overrides.

    The margin left override.

    The selected cells.

    The selected tables.

withDeleteTable

Parameters

Collapse all

    The editor instance.

withGetFragmentTable

Parameters

Collapse all

    The editor instance.

withInsertFragmentTable

Parameters

Collapse all

    The editor instance.

    The plate plugin.

withInsertTextTable

Parameters

Collapse all

    The editor instance.

    The plate plugin.

withNormalizeTable

Parameters

Collapse all

    The editor instance.

withSelectionTable

Parameters

Collapse all

    The editor instance.

withSetFragmentDataTable

Parameters

Collapse all

    The editor instance.

withTable

Enhance the editor instance with table-related functionality.

Parameters

Collapse all

    The editor instance.

    The plate plugin.

ReturnsPlateEditor

    The enhanced editor instance with table functionality:

    • 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