Clipboard Plugin

The Clipboard plugin brings familiar copy/paste functionality to your grid with full keyboard shortcut support (Ctrl+C, Ctrl+V). It handles single cells, multi-cell selections, and integrates seamlessly with Excel and other spreadsheet applications via tab-delimited output.

Tip

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

Installation

import '@toolbox-web/grid/features/clipboard';

Basic Usage

Just enable the feature and you’re ready to go—keyboard shortcuts work automatically. Configure options like includeHeaders for copying column headers or delimiter for custom CSV formats.

TypeScript

import { queryGrid } from '@toolbox-web/grid';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' }
  ],
  features: {
    clipboard: {
      includeHeaders: true,
      quoteStrings: true, // Wrap text in quotes for CSV compatibility
    },
  },
};

React

import '@toolbox-web/grid-react/features/selection';
import '@toolbox-web/grid-react/features/clipboard';
import { DataGrid } from '@toolbox-web/grid-react';
import type { GridConfig } from '@toolbox-web/grid-react';

const gridConfig: GridConfig = {
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' }
  ],
  features: {
    selection: 'range',
    clipboard: { includeHeaders: true, quoteStrings: true },
  },
};

function MyGrid({ data }) {
  return <DataGrid rows={data} gridConfig={gridConfig} style={{ height: '400px' }} />;
}

Alternative: feature prop

You can instead pass columns={[ … ]}, selection="range", and clipboard={{ … }} as individual props on <DataGrid>. That form is idiomatic React, but gridConfig keeps the configuration identical across every framework.

Vue

<script setup>
import '@toolbox-web/grid-vue/features/selection';
import '@toolbox-web/grid-vue/features/clipboard';
import { TbwGrid } from '@toolbox-web/grid-vue';
import type { GridConfig } from '@toolbox-web/grid-vue';

const data = [
  { name: 'Alice', email: 'alice@example.com', department: 'Engineering' },
  { name: 'Bob', email: 'bob@example.com', department: 'Marketing' },
];

const gridConfig: GridConfig = {
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
    { field: 'department', header: 'Department' },
  ],
  features: {
    selection: 'range',
    clipboard: { includeHeaders: true, quoteStrings: true },
  },
};
</script>

<template>
  <TbwGrid :rows="data" :grid-config="gridConfig" style="height: 400px" />
</template>

Alternative: prop + light-dom columns

You can instead set selection="range", bind :clipboard="{ … }", and declare columns with <TbwGridColumn> children. That form is idiomatic Vue, but gridConfig keeps the configuration identical across every framework.

Angular

import '@toolbox-web/grid-angular/features/selection';
import '@toolbox-web/grid-angular/features/clipboard';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { GridConfig } from '@toolbox-web/grid-angular';

@Component({
  selector: 'app-my-grid',
  imports: [Grid],
  template: `
    <tbw-grid
      [rows]="rows"
      [gridConfig]="gridConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class MyGridComponent {
  rows = [...];

  gridConfig: GridConfig = {
    columns: [
      { field: 'name', header: 'Name' },
      { field: 'email', header: 'Email' },
      { field: 'department', header: 'Department' }
    ],
    features: {
      selection: 'range',
      clipboard: { includeHeaders: true, quoteStrings: true },
    },
  };
}

Alternative: per-feature directive

You can instead import GridSelectionDirective and GridClipboardDirective and bind [selection] and [clipboard] directly on <tbw-grid>. That form gives a compile-time check that the features are imported, but gridConfig.features above is the recommended, framework-consistent approach.

Demos

Default Clipboard

CLIPBOARD

Include headersInclude column headers when copying

Quote stringsWrap string values in quotes

External Clipboard Target

Show source

Select cells and use Ctrl+C to copy, Ctrl+V to paste.

Copy & Paste (Auto-Paste)

X1 Y1 Z1 X2 Y2 Z2

Try it: Select the sample data above → Ctrl+C → Click a cell in the grid → Ctrl+V to paste.
Or paste tab/comma-separated data from Excel or Sheets!
Also try to select an area to paste in. Pasting will be restricted to that area only.

Show source

By default, the ClipboardPlugin handles paste operations automatically—no event handling needed. Just add the plugin and paste works out of the box.

Custom Paste Handler

Show source

For advanced use cases, provide a custom pasteHandler to validate, transform, or integrate with state management.

Single Cell Mode

Click a cell and press Ctrl+C to copy its value. No range selection — only the focused cell is copied.

Show source

Without a SelectionPlugin, the clipboard operates on a single focused cell — press Ctrl+C to copy just that cell’s value.

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
escapeFormulas	boolean	true	Prefix values starting with =, +, -, @, tab or CR with ' so a spreadsheet treats them as text. Since 3.5.0
fillSelection	boolean	false	Tile the clipboard source to fill a larger multi-cell selection (see Fill Selection)
processCell	(value, field, row) => string	-	Custom cell value processor for copy operations
pasteHandler	PasteHandler | null	defaultPasteHandler	Custom paste handler. Set to null to disable auto-paste and handle the paste event manually

Per-Column Paste Guard/Transform (column.onPaste)

Use column.onPaste for cell-level paste rules without replacing the whole paste pipeline:

• false rejects pastes into that column,
• (ctx) => false rejects a specific cell,
• (ctx) => ({ value }) transforms the incoming value,
• omitted / true accepts as-is.

columns: [
  { field: 'id', onPaste: false },
  {
    field: 'price',
    onPaste: ({ value, sourceField }) => {
      // Reject cross-column pastes into this field.
      if (sourceField && sourceField !== 'price') return false;
      const n = Number(String(value).replace(/[^0-9.]/g, ''));
      return Number.isFinite(n) ? { value: n } : false;
    },
  },
];

Cells rejected by onPaste emit one paste-rejected event per paste with a list of rejected cells.

Note

If you provide a custom pasteHandler, you should still call resolveColumnPaste() and emitPasteRejected() from @toolbox-web/grid/plugins/clipboard so onPaste and paste-rejected continue to work.

Paste Behavior

The clipboard plugin respects both selection bounds and the editable column property when pasting:

Editable Columns

Paste only works on columns marked editable: true. Non-editable columns are skipped during paste, preserving column alignment:

columns: [
  { field: 'id', header: 'ID' },                    // NOT editable - paste skipped
  { field: 'name', header: 'Name', editable: true }, // Paste allowed
  { field: 'email', header: 'Email', editable: true }, // Paste allowed
]

If you paste "1\t2\t3" into this grid, only the name and email columns receive values (2 and 3). The id column remains unchanged.

Note

Paste editability is resolved by the EditingPlugin (via its getCellEditableResolver query), which also honors row-conditional editable: (row) => boolean. Load the EditingPlugin for paste to write into cells — marking a column editable: true gates paste without you having to trigger interactive editing, but with no EditingPlugin loaded every cell is treated as non-editable and paste is a no-op.

Dirty Tracking, Undo & Validation

When your grid has a getRowId and the EditingPlugin loaded, paste routes each cell change through the same commit pipeline as an interactive edit. That means a paste automatically:

• marks rows dirty (surfaces in isDirty() / getDirtyRows() when dirtyTracking: true),
• is undoable with the UndoRedoPlugin (Ctrl+Z reverts the whole paste),
• emits cell-commit per cell — a handler that calls preventDefault() vetoes that value, so you can coerce or reject pasted input,
• triggers cascades and other editing side effects.

grid.addEventListener('cell-commit', (e) => {
  // Reject a pasted value that fails validation.
  if (e.detail.field === 'age' && Number.isNaN(Number(e.detail.value))) {
    e.preventDefault();
  }
});

Note

Rows without a resolvable getRowId (and freshly-created empty rows when a paste grows the grid) fall back to a direct write that bypasses the pipeline. Configure getRowId to make paste fully dirty-tracked and undoable.

Copied Headers

When includeHeaders: true, copied text carries a header row so it round-trips cleanly to spreadsheets and text editors. Pasting back into cells drops that header row automatically — only values land in cells, never the header label. The header is stripped when the pasted first row consists entirely of this grid’s column labels, so it is removed even for a cross-column paste (copy one column, paste into another), while external pastes without a matching header row are left intact.

Structured Values (Same-Grid & Cross-Window Paste)

Copy is WYSIWYG for external targets — processCell (or the column format) turns each cell into text, so pasting into a spreadsheet or editor looks right. At the same time the grid writes a structured payload: it keeps the raw cell values in memory and embeds them in a text/html representation on the clipboard.

When you paste back into a grid — the same grid, another grid, or another browser window/tab — those raw values are restored, so an object-valued cell (e.g. { id, name }, arrays) round-trips losslessly instead of degrading to its display text. The same-grid path uses the in-memory snapshot (preserving exact value types such as Date); cross-grid / cross-window uses the text/html payload. Each pasted cell is cloned, so tiling one source across many cells (fill-selection) never shares a reference, and array→cells pastes (equal or unequal counts, expansion, and clipping) behave exactly like a text paste.

For an external paste into an object column (e.g. from Excel), only text is available; the grid can’t reconstruct an arbitrary object shape from a string, so your app decides how to handle it (e.g. reject via validation, or map the text to a lookup).

Selection Bounds

Selection Type	Paste Behavior
Single cell	Paste expands freely from that cell, adding rows if needed
Range selection	Paste is clipped to fit within the selected range
Row selection	Paste is clipped to the selected rows (all columns within those rows)
No active range	Paste starts at the selection anchor/focused cell when available; otherwise row 0, column 0

Example: If you have a 2×2 range selected and paste 3×3 data, only the 2×2 portion that fits will be applied.

Fill Selection

With fillSelection: true, pasting a source that is smaller than a bounded multi-cell selection tiles (repeats) the source to fill the whole selection. This is handy for applying one value across many cells without copying it repeatedly.

new ClipboardPlugin({ fillSelection: true });

Copied source	Selection	Result
1 cell	4 cells	value repeated in all 4 cells
v1, v2	4 cells	v1, v2, v1, v2
2×2 block	4×4 range	the block tiled four times

Fill only applies to a bounded (multi-cell) selection and never grows the grid. Non-editable columns are still skipped. When fillSelection is false (the default), paste writes only the source extent.

Keyboard Shortcuts

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

Programmatic API

The ClipboardPlugin exposes methods for programmatic copy operations with fine-grained control over which columns and rows to include. This is ideal for workflows where users select rows in the grid, then choose columns via a dialog before copying.

Basic Copy

const plugin = grid.getPluginByName('clipboard');

// Copy current selection to clipboard
await plugin.copy();

// Copy with headers included
await plugin.copy({ includeHeaders: true });

Copy with Column/Row Control (CopyOptions)

The copy() method accepts CopyOptions to precisely control what gets copied—independently of the current selection:

const plugin = grid.getPluginByName('clipboard');

// Copy specific columns from specific rows
await plugin.copy({
  rowIndices: [0, 3, 7],         // Non-contiguous rows supported
  columns: ['name', 'email'],    // Only these columns
  includeHeaders: true,
});

// Copy specific rows with all visible columns
await plugin.copyRows([0, 5]);

// Copy specific rows with column filter
await plugin.copyRows([0, 5], { columns: ['name', 'department'] });

Preview Without Copying

Use getSelectionAsText() to get the formatted text without writing to the clipboard—useful for preview dialogs:

const text = plugin.getSelectionAsText({
  columns: ['name', 'email', 'department'],
  includeHeaders: true,
});
// "Name\tEmail\tDepartment\nAlice\talice@example.com\tEngineering\n..."

CopyOptions Reference

Option	Type	Default	Description
columns	string[]	-	Specific column fields to include
rowIndices	number[]	-	Specific row indices to copy (non-contiguous OK)
includeHeaders	boolean	config value	Include column headers in copied text
delimiter	string	config value	Column delimiter override
newline	string	config value	Row delimiter override
processCell	(value, field, row) => string	config value	Custom cell value processor for this operation

Paste

// Paste from clipboard
await plugin.paste();

// Get last copied info
const lastCopied = plugin.getLastCopied();
// { text: '...', timestamp: 1234567890 }

Excel Compatibility

The default tab delimiter ensures copied data pastes correctly into Excel:

features: {
  clipboard: {
    delimiter: '\t', // Tab for Excel
    includeHeaders: true, // Include column names
  },
},

Events

Select cells and use Ctrl+C / Ctrl+V to copy and paste.

Event Log:Clear

Event	Detail	Description
copy	{ text, rowCount, columnCount }	Fired after cells are copied
paste	{ rows, text, target, fields, rawRows?, sourceFields?, fillSelection? }	Fired before data is applied (default handler or custom pasteHandler can consume it)
paste-rejected	{ rejected: PasteRejectedCell[] }	Fired when one or more cells are rejected by column onPaste

Styling

The clipboard plugin doesn’t add visible UI elements. Selection styling is handled by the SelectionPlugin.

See Also

• Selection — Cell and row selection
• Editing — Inline cell editing
• Export — Export to CSV/JSON