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';

Configuration Options

Option	Type	Default	Description
includeHeaders	boolean	false	Include column headers in copied data
delimiter	string	'\t'	Column delimiter (tab for Excel compatibility)
newline	string	'\n'	Row delimiter
quoteStrings	boolean	false	Wrap string values in quotes
processCell	(value, field, row) => string	-	Custom cell value processor
pasteHandler	PasteHandler | null	defaultPasteHandler	Custom paste handler

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

Programmatic API

Method	Signature	Description
copy	(options?: CopyOptions) => Promise<string>	Copy to clipboard with optional column/row control
copyRows	(indices, options?) => Promise<string>	Copy specific rows to clipboard
paste	() => Promise<string[][] | null>	Read and parse clipboard content
getSelectionAsText	(options?: CopyOptions) => string	Get clipboard text without writing to clipboard
getLastCopied	() => { text, timestamp } | null	Get info about last copy operation

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

---