quill-table-better

When loading existing content (e.g., from a database), use updateContents instead of setContents to ensure tables render correctly.

const delta = quill.clipboard.convert({ html });
const [range] = quill.selection.getRange();
quill.updateContents(delta, Quill.sources.USER);
quill.setSelection(
  delta.length() - (range?.length || 0),
  Quill.sources.SILENT
);
quill.scrollSelectionIntoView();

Install the package using npm to enhance Quill's table functionality. Ensure you are using Quill v2.0.0 or higher.

npm i quill-table-better

The TableToolbar module implements a dual-mode interaction pattern based on the current selection state:

1. Cell Selection Mode: If cellSelection.selectedTds.length > 1, the toolbar acts on the entire selected cell range. For <select> elements, it uses cellSelection.getCorrectValue to resolve the value and applies it via cellSelection.setSelectedTdsFormat. For buttons, it applies the format to the selected cells and prevents default browser behavior.

2. Standard Mode: If no cells are selected, the toolbar behaves like a standard Quill toolbar, applying formats to the current text range using this.quill.format or custom handlers.

This allows users to format entire table structures (like turning a row into a header) or just format text within a single cell using the same toolbar UI.

The quill-table-better plugin uses a nested hierarchy of Parchment blots to represent tables. Understanding this hierarchy is essential for manipulating table elements via the API.

Hierarchy Overview:

• TableContainer (the <table> element)
  • TableThead (<thead>)
    • TableThRow (<tr> for headers)
      • TableTh (<th>)
        • TableCellBlock (the content block inside a cell)
  • TableBody (<tbody>)
    • TableRow (<tr>)
      • TableCell (<td>)
        • TableCellBlock (the content block inside a cell)
  • TableColgroup (<colgroup>)
    • TableCol (<col>)

Cell Content: Every cell (TableCell or TableTh) contains a block-level element (typically TableCellBlock, which renders as a <P> tag) to hold text or other content. This ensures valid HTML structure where text is not direct children of <td> or <th>.

When initializing the Table module in Quill, you can provide an Options object to customize its behavior.

Available options:

• language: A string identifier or an object { name: string, content: Props } to localize the table UI.
• menus: An array of strings specifying which menus to enable.
• toolbarButtons: Configuration for the table toolbar buttons:
  • whiteList: An array of allowed button names.
  • singleWhiteList: An array of allowed button names for single-mode selection.
• toolbarTable: A boolean. If set to true, it enables the ToolbarTable module and integrates a table selection UI into the existing Quill toolbar.

// Example configuration object
const options = {
  language: 'en',
  menus: ['row', 'col'],
  toolbarButtons: {
    whiteList: ['insert-row', 'delete-row'],
    singleWhiteList: ['insert-col']
  },
  toolbarTable: true
};

You can control which formatting buttons are enabled or disabled during cell selection by configuring whiteList and singleWhiteList within the toolbarButtons option of quill-table-better.

• whiteList: A list of formats that are allowed when multiple cells are selected. If a toolbar button's format is not in this list, it will be disabled when multiple cells are selected.
• singleWhiteList: A list of formats that are only allowed when a single cell is selected. If a format is in this list, the button will be disabled if more than one cell is selected.

By default, the plugin uses internal defaults for these lists.

When all cells in a row or column are selected, you can use the following key combinations to delete the cells and their contents:

• Ctrl + Backspace
• Ctrl + Delete

The following formats are supported for simultaneous operations on multiple cells (WHITE_LIST):

const WHITE_LIST = [
  'bold',
  'italic',
  'underline',
  'strike',
  'size',
  'color',
  'background',
  'font',
  'list',
  'header',
  'align',
  'link',
  'image'
];

Only the following formats are supported for single-cell formatting (SINGLE_WHITE_LIST):

const SINGLE_WHITE_LIST = ['link', 'image'];