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

  • 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

Installation

npm install @udecode/plate-table

Usage

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

Plugins

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

TableRowPlugin

Plugin for table rows.

TableCellPlugin

Plugin for table cells.

TableCellHeaderPlugin

Plugin for table header cells.

API

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

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.

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

Gets the children of a table cell.

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.

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

Gets the column span of a table cell.

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

Gets the row span of a table cell.

Parameters

Collapse all

    The table cell element to get the row span for.

Returnsnumber

    The number of rows this cell spans.

    • Default: 1

getCellType

Get the plugin cell types.

Returnsstring[]

    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

    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

Gets the previous cell in the table.

Parameters

Collapse all

    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

Gets the number of columns in a table.

Parameters

Collapse all

    The table node for which to retrieve the column count.

Returnsnumber

    The number of columns in the table.

getTableColumnIndex

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

Parameters

Collapse all

    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.

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.

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.

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

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

Parameters

Collapse all

    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

Gets the cell above the current cell in the table.

Parameters

Collapse all

    The border direction to check.

Returnsboolean

    true if the border is hidden, false otherwise.

moveSelectionFromCell

Moves the selection by cell unit within a table.

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

Handles keyboard events for table cells.

Parameters

Collapse all

    The plate plugin.

ReturnsKeyboardHandlerReturnType

    The keyboard handler return type.

setBorderSize

Sets the border size of a table cell.

Parameters

Collapse all

    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

    Options for setting column size.

    Additional options for finding the table node.

Optionsobject

Collapse all

    The index of the column to set the width.

    The desired width of the column.

setTableMarginLeft

Sets the margin left of a table.

Parameters

Collapse all

    Options for setting table margin.

    Additional options for finding the table node.

Optionsobject

Collapse all

    The desired margin left value.

setTableRowSize

Sets the size of a table row.

Parameters

Collapse all

    Options for setting row size.

    Additional options for finding the table node.

Optionsobject

Collapse all

    The index of the row to set the size.

    The desired height of the row.

TablePlugin

Plugin for table functionality.

Optionsobject

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

Checks if a table cell is currently selected.

Parameters

Collapse all

    The table cell element to check.

Returnsboolean

    Whether the cell is currently selected.

useSelectedCells

Gets the currently selected table cells.

ReturnsTElement[] | null

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

useTableBordersDropdownMenuContentState

Gets the state of the table borders dropdown menu.

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

Gets the state of a table cell element.

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

Gets the resizable properties of a table cell element.

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

Gets the column sizes of a table.

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

Gets the state of a table element.

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

Gets the table store.

State

Collapse all

    The column size overrides.

    The row size overrides.

    The margin left override.

    The selected cells.

    The selected tables.

withDeleteTable

Overrides the editor's delete behavior to handle table-specific deletion logic.

withGetFragmentTable

Overrides the editor's getFragment behavior to handle table-specific fragment logic. When getting a fragment that includes table cells:

withInsertFragmentTable

Parameters

Collapse all

    The plate plugin.

withInsertTextTable

Handles inserting text within a table.

Parameters

Collapse all

    The plate plugin.

withNormalizeTable

Normalizes the table structure and content.

withSelectionTable

Handles adjusting the selection within a table.

withSetFragmentDataTable

Handles setting the fragment data when copying or cutting table data.

withTable

Enhance the editor instance with table-related functionality.

Parameters

Collapse all

    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