Change copy and paste
Replace the text of a copied cell, the value of a pasted cell, or the whole pasted block with your own functions.
Three props replace one step of copy or paste. Use them to write a cell in your own format. Use them to read a pasted value your way, or to check a pasted block before it lands. Clipboard describes the default behavior.
Before you start
Mount a grid with columns and data. Then pass processCellForClipboard for the copied text, processCellFromClipboard for the pasted values, and processPaste for the whole block.
Change one cell
Each prop runs for every cell or paste. The text and fromText fields of the context hold the default, so return them for the cells you do not change.
This sample writes prices with a $ sign and reads them back:
import {
DataGrid,
defineColumns,
type ClipboardCopyCtx,
type ClipboardPasteCtx,
} from "@/components/data-grid/data-grid";
type Row = { id: string; name: string; price: number };
const rows: Row[] = [{ id: "1", name: "Pen", price: 1.5 }];
const columns = defineColumns<Row>()([
{ id: "name", header: "Name", accessorKey: "name" },
{ id: "price", header: "Price", accessorKey: "price", type: "number" },
]);
function copyText(value: unknown, { column, text }: ClipboardCopyCtx<Row>) {
return column.id === "price" ? `$${value}` : text;
}
function pasteValue(text: string, ctx: ClipboardPasteCtx<Row>) {
if (ctx.column.id !== "price") return ctx.fromText(text);
return ctx.fromText(text.replace("$", ""));
}
function MyGrid() {
return (
<DataGrid
defaultData={rows}
columns={columns}
processCellForClipboard={copyText}
processCellFromClipboard={pasteValue}
/>
);
}processCellForClipboard(value, { row, column, text })returns the text of one copied cell.textis thetoTextof the cell type. Without the prop,textis copied.processCellFromClipboard(text, { row, column, fromText })returns the value of one pasted cell.fromTextparsestextwith the parser of the column. Without the prop, that parser decides.
Change the whole paste
processPaste({ cells, target, signal }) receives the text grid after the parse and the single-row tiling. target is the top-left cell of the paste. Return the grid to write, or false to veto the whole paste.
signal is an AbortSignal. It aborts when the grid turns readOnly, an edit starts, gateTimeoutMs runs out, or the grid unmounts. See Async gates.
processPaste and processCellFromClipboard also accept a promise. ctx.signal is the same signal. This function sends the pasted block to your server:
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
type Row = { id: string; name: string };
const rows: Row[] = [{ id: "1", name: "Pen" }];
const columns = defineColumns<Row>()([
{ id: "name", header: "Name", accessorKey: "name" },
]);
async function processPaste({
cells,
signal,
}: {
cells: string[][];
signal: AbortSignal;
}) {
const response = await fetch("/api/normalize-paste", {
method: "POST",
body: JSON.stringify(cells),
signal,
});
return response.ok ? ((await response.json()) as string[][]) : false;
}
function MyGrid() {
return (
<DataGrid
defaultData={rows}
columns={columns}
processPaste={processPaste}
/>
);
}The grid caps the returned grid at 200,000 cells, so a bad answer cannot grow the paste.
The grid holds the paste until the promise settles, then writes one change. A newer paste replaces the pending one. A rejection cancels the paste.
The grid drops a late result when one of these happens:
- The grid went
readOnly. - A cell editor opened.
- A newer paste started and replaced it.
- The grid unmounted.
- The row or the column under the paste is gone.
- A sort or a filter changed.
If a row operation moved the target row, the paste follows it. The Async gates example shows the gate.
Result
Copy writes $1.5 for the price, and a paste of $1.5 stores 1.5. A processPaste that returns false writes nothing.
Related
- Clipboard: the props table and the default steps.
- Async gates
- Row validation and async checks