ClipboardPlugin

Clipboard Plugin for tbw-grid

Brings familiar copy/cut/paste functionality with full keyboard shortcut support (Ctrl+C, Ctrl+X, Ctrl+V). Handles single cells, multi-cell selections, and integrates seamlessly with Excel and other spreadsheet applications via tab-delimited output.

> Optional Dependency: Works best with SelectionPlugin for copying/pasting selected > cells. Without SelectionPlugin, copies the entire grid and pastes at row 0, column 0.

Installation

import { ClipboardPlugin } from '@toolbox-web/grid/plugins/clipboard';

Keyboard Shortcuts

Shortcut	Action
Ctrl+C / Cmd+C	Copy selected cells
Ctrl+V / Cmd+V	Paste into selected cells
Ctrl+X / Cmd+X	Cut selected cells

Paste Behavior by Selection Type

Selection Type	Paste Behavior
Single cell	Paste expands freely from that cell
Range selection	Paste is clipped to fit within the selected range
Row selection	Paste is clipped to the selected rows
No selection	Paste starts at row 0, column 0

Configuration Options

Option	Type	Description
includeHeaders?	boolean	Include column headers in copied text (default: false)
delimiter?	string	Column delimiter character (default: ‘\t’ for tab)
newline?	string	Row delimiter/newline character (default: ‘\n’)
quoteStrings?	boolean	Wrap string values with quotes (default: false)
processCell?	(value: unknown, field: string, row: unknown) => string	Custom cell value processor for copy operations
pasteHandler?	PasteHandler | unknown	Custom paste handler. By default, the plugin applies pasted data to grid.rows starting at the target cell.

Examples

Basic Usage with Excel Compatibility

import '@toolbox-web/grid';
import { ClipboardPlugin } from '@toolbox-web/grid/plugins/clipboard';
import { SelectionPlugin } from '@toolbox-web/grid/plugins/selection';

grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
  ],
  plugins: [
    new SelectionPlugin({ mode: 'range' }),
    new ClipboardPlugin({
      includeHeaders: true,
      delimiter: '\t', // Tab for Excel
    }),
  ],
};

Custom Paste Handler

new ClipboardPlugin({
  pasteHandler: (grid, target, data) => {
    // Validate or transform data before applying
    console.log('Pasting', data.length, 'rows');
    return defaultPasteHandler(grid, target, data);
  },
})

See Also

• ClipboardConfig for all configuration options
• SelectionPlugin for enhanced copy/paste with selection

Extends BaseGridPlugin

Inherited methods like attach(), detach(), afterRender(), etc. are documented in the base class.

Methods

getSelectionAsText()

Get the text representation of the current selection (or specified data) without writing to the system clipboard.

Useful for previewing what would be copied, or for feeding the text into a custom UI (e.g., a “copy with column picker” dialog).

getSelectionAsText(options: CopyOptions): string

Parameters

Name	Type	Description
options	CopyOptions	Control which columns/rows to include

Returns

string - Delimited text, or empty string if nothing to copy

Example

const clipboard = grid.getPluginByName('clipboard');
const text = clipboard.getSelectionAsText({
  columns: ['name', 'email'],
  includeHeaders: true,
});
console.log(text);
// "Name\tEmail\nAlice\talice@example.com\n..."

---

copy()

Copy data to the system clipboard.

Without options, copies the current selection (or entire grid if no selection). With options, copies exactly the specified columns and/or rows — ideal for “copy with column picker” workflows where the user selects rows first, then chooses which columns to include via a dialog.

copy(options: CopyOptions): Promise<string>

Parameters

Name	Type	Description
options	CopyOptions	Control which columns/rows to include

Returns

Promise<string> - The copied text

Example

const clipboard = grid.getPluginByName('clipboard');
await clipboard.copy();

---

copyRows()

Copy specific rows by index to clipboard.

Convenience wrapper around copy for row-based workflows. Supports non-contiguous row indices (e.g., [0, 3, 7]).

copyRows(indices: number[], options: Omit<CopyOptions, "rowIndices">): Promise<string>

Parameters

Name	Type	Description
indices	number[]	Array of row indices to copy
options	Omit<CopyOptions, rowIndices>	Additional copy options (columns, headers, etc.)

Returns

Promise<string> - The copied text

Example

const clipboard = grid.getPluginByName('clipboard');
// Copy only rows 0 and 5, including just name and email columns
await clipboard.copyRows([0, 5], { columns: ['name', 'email'] });

---

paste()

Read and parse clipboard content.

paste(): Promise<string[][] | null>

Returns

Promise<string[][] | null> - Parsed 2D array of cell values, or null if clipboard is empty

---

getLastCopied()

Get the last copied text and timestamp.

getLastCopied(): object | null

Returns

object | null - The last copied info or null

---