The Basics: Copy, Cut, and Paste

Out of the box, AG-Grid supports standard clipboard operations using familiar keyboard shortcuts, much like a spreadsheet application:

• Copy (Ctrl+C / Cmd+C): Copies selected cells or rows to the clipboard.
• Paste (Ctrl+V / Cmd+V): Pastes data from the clipboard into the grid. If a single cell is selected, the paste starts from there. If a range is selected, it attempts to paste into that range.
• Cut (Ctrl+X / Cmd+X): Copies selected cells to the clipboard and then clears their content in the grid.

By default, if you select a range of cells and press Ctrl+C, the data will be copied to your system clipboard, usually tab-separated. When you paste this data back into the grid (or another application like Excel), it will maintain its structure.

Configuring Clipboard Behavior

AG-Grid offers several grid options to fine-tune how clipboard operations behave:

enableCellTextSelection: boolean

Set to true to allow users to select text within cells directly with the mouse, rather than starting a range selection. This is useful for copying text without affecting the grid's selection model.

suppressClipboardPaste: boolean

If true, the grid will not respond to paste operations (Ctrl+V / Cmd+V).

suppressCopyRowsToClipboard: boolean

If true, when copying (e.g., Ctrl+C on a selected row), only the selected cells will be copied, not the entire row if no specific cells are selected.

suppressCutToClipboard: boolean

If true, the grid will not respond to cut operations (Ctrl+X / Cmd+X).

clipboardDelimiters: string[]

An array of strings used to determine how pasted data is delimited. By default, it includes ['\t'] (tab). You can add others like [',', '\t'] to allow pasting comma-separated values.

Customizing Cell Data for Copy/Paste

One of the most powerful features is the ability to transform cell data just before it's copied or after it's pasted. This is invaluable for handling complex data types, formatting, or combining/splitting values.

processCellForClipboard(params): any

This callback allows you to modify the value of a cell before it's copied to the clipboard. The params object contains value, node, colDef, column, api, and columnApi. You return the transformed value.

Use cases:

• Formatting dates into a specific string format.
• Exporting numerical values without currency symbols.
• Combining multiple cell values into a single clipboard value.

const gridOptions = {
    processCellForClipboard: params => {
        if (params.colDef.field === 'date') {
            return params.value ? new Date(params.value).toLocaleDateString('en-GB') : '';
        }
        if (params.colDef.field === 'price') {
            return params.value.replace('$', ''); // Remove currency symbol
        }
        return params.value;
    },
    // ... other options
};

processCellFromClipboard(params): any

This callback allows you to modify the value of a cell after it's been read from the clipboard but before it's set on the cell. The params object is similar to processCellForClipboard but also includes clipboardText.

Use cases:

• Parsing dates from clipboard text into a Date object or specific format.
• Converting text (e.g., 'true', 'false') to boolean values.
• Splitting a single pasted value into multiple cell values (though processDataFromClipboard might be better for this).

const gridOptions = {
    processCellFromClipboard: params => {
        if (params.colDef.field === 'date') {
            // Attempt to parse date string from clipboard
            const date = new Date(params.clipboardText);
            return isNaN(date.getTime()) ? null : date.toISOString().slice(0, 10); // Store as YYYY-MM-DD
        }
        if (params.colDef.field === 'isActive') {
            return params.clipboardText.toLowerCase() === 'true';
        }
        return params.clipboardText;
    },
    // ... other options
};

processDataFromClipboard(params): string[][]

This callback is more advanced and gives you full control over the raw data received from the clipboard, typically in a 2D array format. You can transform the entire block of data before AG-Grid attempts to map it to cells.

Use cases:

• Transposing data (rows to columns, columns to rows).
• Performing global find-and-replace operations on pasted data.
• Handling custom delimiters not covered by clipboardDelimiters.

const gridOptions = {
    processDataFromClipboard: params => {
        // Example: Convert all pasted text to uppercase
        return params.data.map(row => row.map(cellValue => String(cellValue).toUpperCase()));
    },
    // ... other options
};

Programmatic Clipboard Operations

Beyond user-initiated shortcuts, you can programmatically trigger clipboard operations using the grid API.

• api.copySelectedRowsToClipboard(includeHeader?: boolean): Copies all selected rows to the clipboard. Set includeHeader to true to include column headers.
• api.copySelectedRangeToClipboard(includeHeader?: boolean): Copies the currently selected range of cells to the clipboard.
• api.copySelectedCellsToClipboard(includeHeader?: boolean): Copies all individual selected cells to the clipboard.

These methods respect the processCellForClipboard callback.

const onButtonClick = useCallback(() => {
    gridRef.current.api.copySelectedRowsToClipboard(true); // Copy selected rows with headers
}, []);

Clipboard Events

AG-Grid fires events related to clipboard activities, allowing you to react to user actions:

• onPasteStart(): Fired when a paste operation begins.
• onPasteEnd(): Fired when a paste operation finishes.
• onCutStart(): Fired when a cut operation begins.
• onCutEnd(): Fired when a cut operation finishes.
• onCopyStart(): Fired when a copy operation begins.
• onCopyEnd(): Fired when a copy operation finishes.

const gridOptions = {
    onPasteStart: () => console.log('Paste operation started!'),
    onPasteEnd: () => console.log('Paste operation ended!'),
    // ... other options
};

AG-Grid Specific Shortcuts for Productivity

In addition to standard OS clipboard shortcuts, AG-Grid offers some spreadsheet-like shortcuts for data manipulation:

• Ctrl+D / Cmd+D (Fill Down): If a range of cells is selected and the top row has data, this shortcut fills the data downwards into the empty cells of the selection.
• Ctrl+R / Cmd+R (Fill Right): Similar to fill down, but fills data to the right.
• Cell Dragging for Fill: If you enable range selection (docs link if desired), users can drag the small square handle at the bottom-right of a selected range to 'fill' data, replicating spreadsheet behavior.

These features can significantly enhance user productivity within your AG-Grid applications.

Putting It All Together: A React Example

Here's a comprehensive React component demonstrating some of the clipboard configurations discussed:

import React, { useRef, useCallback, useMemo } from 'react';
import { AgGridReact } from 'ag-grid-react';

import 'ag-grid-community/styles/ag-grid.css';
import 'ag-grid-community/styles/ag-theme-alpine.css';

const MyGridComponent = () => {
    const gridRef = useRef();

    const columnDefs = useMemo(() => [
        { field: 'id', headerName: 'ID', width: 80, editable: false },
        { field: 'name', headerName: 'Name', width: 150, editable: true },
        {
            field: 'status',
            headerName: 'Status',
            width: 120,
            editable: true,
            cellEditor: 'agSelectCellEditor',
            cellEditorParams: {
                values: ['Active', 'Inactive', 'Pending'],
            },
        },
        {
            field: 'value',
            headerName: 'Value',
            width: 120,
            editable: true,
            valueFormatter: p => (p.value !== null && p.value !== undefined ? `$${p.value.toFixed(2)}` : ''),
            valueParser: p => parseFloat(p.newValue.replace(/[^0-9.-]+/g, "")), // Remove non-numeric chars for parsing
        },
        {
            field: 'lastUpdated',
            headerName: 'Last Updated',
            width: 180,
            editable: true,
            valueFormatter: p => p.value ? new Date(p.value).toLocaleString() : '',
            cellEditor: 'agDateStringCellEditor', // Use a date editor for input
            cellEditorParams: {
                min: '2020-01-01',
                max: '2024-12-31',
            }
        },
    ], []);

    const rowData = useMemo(() => [
        { id: 1, name: 'Alice', status: 'Active', value: 123.45, lastUpdated: '2023-01-15T10:00:00Z' },
        { id: 2, name: 'Bob', status: 'Inactive', value: 67.89, lastUpdated: '2023-02-20T11:30:00Z' },
        { id: 3, name: 'Charlie', status: 'Pending', value: 200.00, lastUpdated: '2023-03-05T14:45:00Z' },
        { id: 4, name: 'Diana', status: 'Active', value: 99.99, lastUpdated: '2023-04-10T09:00:00Z' },
    ], []);

    // Custom function to process cell values before copying to clipboard
    const processCellForClipboard = useCallback(params => {
        if (params.colDef.field === 'lastUpdated') {
            // Format date specifically for clipboard (e.g., YYYY-MM-DD)
            return params.value ? new Date(params.value).toISOString().slice(0, 10) : '';
        }
        if (params.colDef.field === 'value') {
            // Remove '$' for copying raw number
            return params.value;
        }
        return params.value;
    }, []);

    // Custom function to process cell values from clipboard before pasting
    const processCellFromClipboard = useCallback(params => {
        if (params.colDef.field === 'lastUpdated') {
            // Attempt to parse date string from clipboard, e.g., '2023-01-15'
            const date = new Date(params.clipboardText);
            return isNaN(date.getTime()) ? null : date.toISOString(); // Store as ISO string
        }
        if (params.colDef.field === 'status') {
             // Example: if clipboard has 'active', normalize to 'Active'
            const normalizedStatus = params.clipboardText.charAt(0).toUpperCase() + params.clipboardText.slice(1).toLowerCase();
            const validStatuses = ['Active', 'Inactive', 'Pending'];
            return validStatuses.includes(normalizedStatus) ? normalizedStatus : null; // Return null if invalid
        }
        return params.clipboardText;
    }, []);

    const onGridReady = useCallback((params) => {
        // You could programmatically copy here, e.g., if you have a button
        // gridRef.current.api.copySelectedRowsToClipboard();
    }, []);

    const onPasteEnd = useCallback(() => {
        console.log('Paste operation completed!');
        // Potentially trigger a server update or other logic here
    }, []);

    const onCopyEnd = useCallback(() => {
        console.log('Copy operation completed!');
    }, []);

    return (
        <div className="ag-theme-alpine" style={{ height: 400, width: 700 }}>
            <AgGridReact
                ref={gridRef}
                rowData={rowData}
                columnDefs={columnDefs}
                defaultColDef={{
                    flex: 1,
                    minWidth: 100,
                    resizable: true,
                }}
                // Enable range selection for fill handles and multi-cell operations
                enableRangeSelection={true}
                // Allow users to select text within cells
                enableCellTextSelection={true}
                // Custom clipboard processing
                processCellForClipboard={processCellForClipboard}
                processCellFromClipboard={processCellFromClipboard}
                // Listen to clipboard events
                onPasteEnd={onPasteEnd}
                onCopyEnd={onCopyEnd}
                // Suppress cut operations if desired
                // suppressCutToClipboard={true}
                onGridReady={onGridReady}
            />
        </div>
    );
};

export default MyGridComponent;

Conclusion

AG-Grid's clipboard operations and shortcuts are far more than simple copy-paste. They offer a sophisticated set of tools to empower your users with efficient data interaction, mirroring the advanced capabilities of dedicated spreadsheet applications. By understanding and utilizing the various configuration options and callbacks, you can create a highly intuitive and powerful data editing experience tailored to your application's unique requirements.

Experiment with these features in your AG-Grid React projects to unlock new levels of user productivity. Stay tuned for the next entry in our series, where we'll explore even more ways to master AG-Grid!