{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "table-docs",
"title": "Table",
"description": "Documentation for Table",
"files": [
{
"path": "../../content/docs/(plugins)/(elements)/table.mdx",
"content": "---\ntitle: Table\ndocs:\n - route: https://pro.platejs.org/docs/examples/table\n title: Plus\n - route: /docs/components/table-toolbar-button\n title: Table Toolbar Button\n - route: /docs/components/table-node\n title: Table Nodes\n---\n\n\n\n\n\n## Features\n\n- Enables creation and editing of tables with advanced behaviors.\n- Arrow navigation (up/down).\n- Grid cell selection.\n- Cell selection expansion with `Shift+Arrow` keys.\n- Copying and pasting cells.\n- Row drag-and-drop reordering\n- Row selection via drag handle\n\n\n\n## Kit Usage\n\n\n\n### Installation\n\nThe fastest way to add table functionality is with the `TableKit`, which includes pre-configured `TablePlugin`, `TableRowPlugin`, `TableCellPlugin`, and `TableCellHeaderPlugin` with their [Plate UI](/docs/installation/plate-ui) components.\n\n\n\n- [`TableElement`](/docs/components/table-node): Renders table containers.\n- [`TableRowElement`](/docs/components/table-node): Renders table rows.\n- [`TableCellElement`](/docs/components/table-node): Renders table cells.\n- [`TableCellHeaderElement`](/docs/components/table-node): Renders table header cells.\n\n### Add Kit\n\nAdd the kit to your plugins:\n\n```tsx\nimport { createPlateEditor } from 'platejs/react';\nimport { TableKit } from '@/components/editor/plugins/table-kit';\n\nconst editor = createPlateEditor({\n plugins: [\n // ...otherPlugins,\n ...TableKit,\n ],\n});\n```\n\n\n\n## Manual Usage\n\n\n\n### Installation\n\n```bash\nnpm install @platejs/table\n```\n\n### Add Plugin\n\nInclude `TablePlugin` in your Plate plugins array when creating the editor.\n\n```tsx\nimport { TablePlugin } from '@platejs/table/react';\nimport { createPlateEditor } from 'platejs/react';\n\nconst editor = createPlateEditor({\n plugins: [\n // ...otherPlugins,\n TablePlugin,\n ],\n});\n```\n\n### Configure Plugins\n\nConfigure the table plugins with custom components and options.\n\n```tsx\nimport {\n TableCellHeaderPlugin,\n TableCellPlugin,\n TablePlugin,\n TableRowPlugin,\n} from '@platejs/table/react';\nimport { createPlateEditor } from 'platejs/react';\nimport {\n TableCellElement,\n TableCellHeaderElement,\n TableElement,\n TableRowElement,\n} from '@/components/ui/table-node';\n\nconst editor = createPlateEditor({\n plugins: [\n // ...otherPlugins,\n TablePlugin.configure({\n node: { component: TableElement },\n options: {\n initialTableWidth: 600,\n disableMerge: false,\n minColumnWidth: 48,\n },\n }),\n TableRowPlugin.withComponent(TableRowElement),\n TableCellPlugin.withComponent(TableCellElement),\n TableCellHeaderPlugin.withComponent(TableCellHeaderElement),\n ],\n});\n```\n\n- `node.component`: Assigns [`TableElement`](/docs/components/table-node) to render table containers.\n- `withComponent`: Assigns components for table rows, cells, and header cells.\n- `options.initialTableWidth`: Sets the initial width for new tables.\n- `options.disableMerge`: Disables cell merging functionality.\n- `options.minColumnWidth`: Sets the minimum width for table columns.\n\n### Add Toolbar Button\n\nYou can add [`TableToolbarButton`](/docs/components/table-toolbar-button) to your [Toolbar](/docs/toolbar) to insert tables.\n\n### Insert Toolbar Button\n\nYou can add this item to the [Insert Toolbar Button](/docs/toolbar#insert-toolbar-button) to insert table elements:\n\n```tsx\n{\n icon: ,\n label: 'Table',\n value: KEYS.table,\n}\n```\n\n### Disable Merging Example\n\n\n\n\n\n## Plugins\n\n### TablePlugin\n\n\n\n \n Disables the merging behavior of cells.\n \n \n Disables the expansion of the table when inserting cells.\n \n \n Disables the left resizer of the first column in the table.\n \n \n 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.\n \n \n 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.\n \n \n The minimum width of a column in the table.\n - **Default:** `48`\n \n\n\n\n### TableRowPlugin\n\nPlugin for table rows.\n\n### TableCellPlugin\n\nPlugin for table cells.\n\n### TableCellHeaderPlugin\n\nPlugin for table header cells.\n\n## API\n\n### editor.api.create.table\n\n\n\n\nExtends `GetEmptyRowNodeOptions`.\n\n\n\n\n\nSpecify `true` if the table has a header row.\n\n\nThe number of rows in the table.\n\n- **Default:** `0`\n\n\n\nThe number of columns in the table.\n\n\n\n\n\n\nThe table node.\n\n\n\n\n\n### editor.api.create.tableCell\n\nCreates an empty cell node for a table.\n\n\n\n\nSpecify `true` if the cell is a header cell.\n\n\nThe row element. If `header` is not specified, it will determine if the cell is a header cell based on the row's children.\n\n\nThe children of the new cell node.\n\n- **Default:** `[editor.api.create.block()]`\n\n\n\n\n\n\n\nThe cell node.\n\n\n\n\n\n### editor.api.create.tableRow\n\nCreates an empty row node with the specified number of columns.\n\n\n\n\nSpecify `true` if the row is a header row.\n\n\nThe number of columns in the row.\n\n- **Default:** `1`\n\n\n\n\n\n\n\nThe row node.\n\n\n\n\n\n### editor.api.table.getCellBorders\n\nGets the border styles for a table cell, handling special cases for first row and first column cells.\n\n\n\n\nThe table cell element to get the border styles for.\n\n\" optional>\nThe default border style to use when cell borders are not defined.\n\n\n The border color.\n - **Default:** `'rgb(209 213 219)'`\n\n\n The border size.\n - **Default:** `1`\n\n\n The border style.\n - **Default:** `'solid'`\n\n\n\n\n\n\n \n An object containing:\n \n \">\n The bottom border style.\n \n \">\n The right border style.\n \n \" optional>\n The left border style. Only present for cells in the first column.\n \n \" optional>\n The top border style. Only present for cells in the first row.\n \n \n \n\n\n\n### editor.api.table.getCellChildren\n\nGets the children of a table cell.\n\n\n\n\nThe table cell element.\n\n\n\n\n\n\nThe children of the table cell.\n\n\n\n\n\n### editor.api.table.getCellSize\n\nGets the width and minimum height of a table cell, taking into account column spans and column sizes.\n\n\n\n\nThe table cell element to get the size for.\n\n\nOptional array of column sizes. If not provided, will use the table's overridden column sizes.\n\n\n\n\n\nThe total width of the cell, calculated by summing the widths of all columns it spans.\n\n\nThe minimum height of the cell, derived from the row's size property.\n\n\n\n\n### editor.api.table.getColSpan\n\nGets the column span of a table cell.\n\n\n\n\nThe table cell element to get the column span for.\n\n\n\n\n \n The number of columns this cell spans.\n - **Default:** `1`\n \n\n \n\n### editor.api.table.getRowSpan\n\nGets the row span of a table cell.\n\n\n\n \n The table cell element to get the row span for.\n \n\n\n\n \n The number of rows this cell spans.\n - **Default:** `1`\n \n\n\n\n### getCellType\n\nGet the plugin cell types.\n\n\n\n\n\n An array of element types for table cells (td and th) in the editor.\n\n\n\n\n\n### getNextTableCell\n\nGets the next cell in the table.\n \n\n\n \n The entry of the current cell.\n \n \n The path of the current cell.\n \n \n The entry of the current row.\n \n\n\n\n \n The node entry of the cell in the next row, or `undefined` if the current\n row is the last row.\n \n\n\n\n### getPreviousTableCell\n\nGets the previous cell in the table.\n\n\n\n \n The entry of the current cell.\n \n \n The path of the current cell.\n \n \n The entry of the current row.\n \n\n\n\n \n The node entry of the cell in the previous row, or `undefined` if the\n current row is the first row.\n \n\n\n\n### getTableColumnCount\n\nGets the number of columns in a table.\n\n\n\n \n The table node for which to retrieve the column count.\n \n\n\n\n\n\nThe number of columns in the table.\n\n\n\n\n### getTableColumnIndex\n\nGets the column index of a cell node within a table.\n\n\n\n \n The cell node for which to retrieve the column index.\n \n\n\n\n\n\nThe column index of the cell node.\n\n\n\n\n\n### getTableEntries\n\nGets the table, row, and cell node entries based on the current selection or a specified location.\n\n\n\n\nThe location where the table cell is located.\n\n- **Default:** `editor.selection`\n\n\n\n\n \n The table node entry.\n \n \n The row node entry.\n \n \n The cell node entry.\n \n\n\n\n\n### getTableGridAbove\n\nGets the sub table above the anchor and focus positions based on the specified format (tables or cells).\n\n\n\n\nThe format of the sub table to retrieve.\n\n- **Default:** `'table'`\n\n\n\n\n\n The sub table entries.\n\n\n### getTableGridByRange\n\nGets the sub table between two cell paths within a given range.\n\n\n\n\nThe range specifying the start and end cell paths.\n\n\nThe format of the output.\n\n- **Default:** `'table'`\n\n\n\n\n\n The sub table entries.\n\n\n\n### getTableRowIndex\n\nGets the row index of a cell node within a table.\n\n\n\n \n The cell node for which to retrieve the row index.\n \n\n\n\n\n\nThe row index of the cell node.\n\n\n\n\n\n### getTopTableCell\n\nGets the cell above the current cell in the table.\n\n\n\n \n The path to the current cell. If not provided, the function will search for\n the current cell in the editor.\n \n\n\n\n\n\nThe cell node entry.\n\n\n\n\n### isTableBorderHidden\n\nChecks if the border of a table cell or the table itself is hidden based on the specified border direction.\n\n\n\n \n The border direction to check.\n \n\n\n\n\n\n`true` if the border is hidden, `false` otherwise.\n\n\n\n\n\n## Editing Behavior\n\nTable editing behavior is split across table transforms and plugin extensions. Use `tf.table.merge` and `tf.table.split` for merge controls, `tf.moveSelectionFromCell` for keyboard navigation out of cells, and the table extension hooks below for deletion, paste, normalization, and fragment handling.\n\n## Transforms\n\n### `tf.insert.table`\n\nInserts a table at the current selection if there is no existing table in the editor. Selects the start of the inserted table.\n\n\n\n\nExtends `GetEmptyRowNodeOptions`.\n\n\nThe number of rows in the table.\n\n- **Default:** `2`\n\n\n\nThe number of columns in the table.\n\n- **Default:** `2`\n\n\n\nIf `true`, the first row of the table will be treated as a header row.\n\n\n\n\n\n\nThe options for inserting the table nodes.\n\n\n\n\n### `tf.insert.tableColumn`\n\nInserts a column into the table at the current selection or a specified cell path.\n\n\n\n\nThe exact path of the cell to insert the column at. This overrules the\n`fromCell` option.\n\n\nIf true, insert the column before the current column instead of after.\n\n\nThe path of the cell to insert the column from.\n\n\nIf true, the inserted column will be treated as a header column.\n\n\nIf true, the inserted column will be selected after insertion.\n\n\n\n\n### `tf.insert.tableRow`\n\nInserts a row into the table at the current selection or a specified row path.\n\n\n\n\nExact path of the row to insert the column at. Pass the table path to\ninsert at the end of the table. Will overrule `fromRow`.\n\n\nIf true, insert the row before the current row instead of after.\n\n\nThe path of the row to insert the new row from.\n\n\nIf true, the inserted row will be treated as a header row.\n\n\nIf true, the inserted row will be selected after insertion.\n\n\n\n\n### `tf.remove.tableColumn`\n\nDeletes the column containing the selected cell in a table.\n\n### `tf.remove.tableRow`\n\nDeletes the row containing the selected cell in a table.\n\n### `tf.remove.table`\n\nDeletes the entire table.\n\n### `tf.table.merge`\n\nMerges multiple selected cells into one.\n\nThe merged cell will:\n- Have a colSpan equal to the number of columns spanned by the selected cells\n- Have a rowSpan equal to the number of rows spanned by the selected cells\n- Contain the combined content of all merged cells (non-empty cells only)\n- Inherit the header status from the first selected cell\n\n### `tf.table.split`\n\nSplits a merged cell back into individual cells.\n\nThe split operation will:\n- Create new cells for each column and row that was spanned\n- Copy the header status from the original merged cell\n- Place the original cell's content in the first cell\n- Create empty cells for the remaining spaces\n\n### `tf.moveSelectionFromCell`\n\nMoves the selection by cell unit within a table.\n\n\n\n\nThe location to move the selection from.\n\n\n Set to `true` to move the selection to the cell above, `false` to move\nthe selection to the cell below.\n\n\nThe edge to expand the cell selection to.\n\n\nSet to `true` to move the selection from only one selected cell.\n\n\n\n\n### `tf.setBorderSize`\n\nSets the size of the specified border in a table cell.\n\n\n\n\nThe size of the border.\n\n\nOptions for setting the border size.\n\n\n\n\n\nThe location of the cell to set the border size.\n\n\nThe border direction to set the size.\n\n- **Default:** `'all'`\n\n\n\n\n\n### `tf.setTableColSize`\n\nSets the width of a specific column in a table.\n\n\n\n\nThe index of the column to set the width.\n\n\nThe desired width of the column.\n\n\nAdditional options for finding the table node.\n\n\n\n\n### `tf.setTableMarginLeft`\n\nSets the margin left of a table.\n\n\n\n\nAn object containing the desired margin left value.\n\n\nAdditional options for finding the table node.\n\n\n\n\n### `tf.setTableRowSize`\n\nSets the size (height) of a table row.\n\n\n\n\nThe index of the row to set the size.\n\n\nThe desired height of the row.\n\n\nAdditional options for finding the table node.\n\n\n\n\n## Plugin Extensions\n\n### `onKeyDownTable`\n\nHandles the keyboard events for tables.\n\n\n\n \n The plate plugin.\n \n\n\n\n \n The keyboard handler return type.\n \n\n\n\n### `withDeleteTable`\n\nPrevents the deletion of cells in tables.\n\n### `withGetFragmentTable`\n\nIf 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.\n\n### `withInsertFragmentTable`\n\nIf inserting a table:\n\n- 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.\n- 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.\n\n### `withInsertTextTable`\n\nIf the selection is expanded:\n\n- Check if the selection is inside a table. If it is, collapse the selection to the focus edge.\n\n### `withNormalizeTable`\n\nNormalize table structure by performing the following actions:\n\n- Wrap cell children in a paragraph if they are texts.\n- Unwrap nodes that are not valid table elements.\n- Set initial column sizes for tables if specified.\n\n### `withSelectionTable`\n\nHandle table selections by performing the following actions:\n\n- 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.\n- 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.\n- Override the selection from a cell if the previous and new selections are in different cells.\n\n### `withSetFragmentDataTable`\n\nHandle setting data to the clipboard when copying or cutting table data by performing the following actions:\n\n- Check if a table entry and selected cell entries exist.\n- Handle single-cell copy or cut operations by copying the cell content instead of the table structure.\n- Create a table structure with the selected cells' content.\n- Set the text, HTML, CSV, TSV, and Slate fragment data to the clipboard.\n\n### `withTable`\n\nEnhance the editor instance with table-related functionality by applying the following higher-order functions:\n\n- `withNormalizeTable`: Normalize table structure and content.\n- `withDeleteTable`: Prevent cell deletion within a table.\n- `withGetFragmentTable`: Handle getting the fragment data when copying or cutting table cells.\n- `withInsertFragmentTable`: Handle inserting table fragments.\n- `withInsertTextTable`: Handle inserting text within a table.\n- `withSelectionTable`: Handle adjusting the selection within a table.\n- `withSetFragmentDataTable`: Handle setting the fragment data when copying or cutting table data.\n\n## Hooks\n\n### `useTableCellElementResizable`\n\nA hook that provides resizing functionality for table cell elements.\n\n\n\n\nThe index of the column.\n\n\nThe number of columns this cell spans.\n\n\n The index of the row.\n\n\nResize by step instead of by pixel.\n\n\nStep size for horizontal resizing.\n\n\nStep size for vertical resizing.\n\n- **Default:** `step`\n\n\n\n\n\n \n Props for the bottom resize handle, including resize direction and handler.\n \n \n Whether the left resize handle should be hidden. True if not the first column or margin left is disabled.\n \n \n Props for the left resize handle, including resize direction and handler.\n \n \n Props for the right resize handle, including resize direction, initial size, and handler.\n \n\n\n \n\n### `useTableStore`\n\nThe table store stores the state of the table plugin.\n\n\n\n \n The column size overrides.\n \n \n The row size overrides.\n \n \n The margin left override.\n \n \n The selected cells.\n \n \n The selected tables.\n \n\n\n\n### `useIsCellSelected`\n\nCustom hook that checks if a table cell is selected.\n\n\n\n \n The table cell element to check.\n \n\n\n\n### `useSelectedCells`\n\nA hook that manages the selection of cells in a table.\n\nIt keeps track of the currently selected cells and updates them based on changes in editor selection.\n\n### `useTableBordersDropdownMenuContentState`\n\nA state hook for the table borders dropdown menu content.\n\n\n\nAn object with the following properties:\n\nIndicates whether the selected table cells have a bottom border.\n\n\nIndicates whether the selected table cells have a top border.\n\n\nIndicates whether the selected table cells have a left border.\n\n\nIndicates whether the selected table cells have a right border.\n\n\nIndicates whether the selected table cells have no borders.\n\n\nIndicates whether the selected table cells have outer borders (i.e.,\nborders on all sides).\n\n\nA factory function that returns the `onSelectTableBorder` handler for a\nspecific border type.\n\n- The `onSelectTableBorder` handler is responsible for setting the border style for the selected table cells.\n\n\n\n\n\n### `useTableColSizes`\n\nCustom 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.\n\n\n\n\nIf `true`, disables applying overrides to the column sizes.\n- **Default:** `false`\n\n\n\n\n \n The column sizes of the table with overrides applied.\n \n\n\n\n### `useTableElement`\n\nA hook for a table element that handles cell selection and margin left calculations.\n\n\n\n \n Whether cells are currently being selected.\n \n \n The margin left of the table, considering overrides and plugin options.\n \n \n Props for the table element:\n \n \n Handler that collapses selection when clicking on the table while cells are selected.\n \n \n \n\n\n \n### `useTableCellElement`\n\nA hook for a table cell element that provides state and functionality for table cells.\n\n\n\n \n The border styles of the table cell.\n \n \n The ending column index (considering colSpan).\n \n \n The number of columns this cell spans.\n \n \n Whether cells are currently being selected.\n \n \n The minimum height of the cell.\n \n \n The ending row index (considering rowSpan).\n \n \n Whether this cell is currently selected.\n \n \n The width of the cell.\n \n\n\n\n### `useTableCellBorders`\n\nA hook that returns the border styles for a table cell.\n\n\n\n \n An object containing the border styles for the cell:\n \n \">\n The bottom border style.\n \n \">\n The right border style.\n \n \" optional>\n The left border style. Only present for cells in the first column.\n \n \" optional>\n The top border style. Only present for cells in the first row.\n \n \n \n\n\n\n### `useTableCellSize`\n\nA hook that returns the size (width and minimum height) of a table cell.\n\n\n\n \n An object containing:\n \n \n The total width of the cell, calculated by summing the widths of all columns it spans.\n \n \n The minimum height of the cell, derived from the row's size property.\n \n \n \n\n\n",
"type": "registry:file",
"target": "content/docs/plate/(plugins)/(elements)/table.mdx"
}
],
"type": "registry:file"
}