JavaScript Data GridCopyPaste

Description

Copy, cut, and paste data by using the CopyPaste plugin.

Control the CopyPaste plugin programmatically through its API methods.

The user can access the copy-paste features through:

Read more:

Example

// enable the plugin with the default configuration
copyPaste: true,

// or, enable the plugin with a custom configuration
copyPaste: {
  columnsLimit: 25,
  rowsLimit: 50,
  pasteMode: 'shift_down',
  copyColumnHeaders: true,
  copyColumnGroupHeaders: true,
  copyColumnHeadersOnly: true,
  uiContainer: document.body,
},

Options

copyPaste

Source code

copyPaste.copyPaste : object | boolean

The copyPaste option configures the CopyPaste plugin.

You can set the copyPaste option to one of the following:

Setting Description
true (default) Enable the CopyPaste plugin with the default configuration
false Disable the CopyPaste plugin
An object - Enable the CopyPaste plugin
- Modify the CopyPaste plugin options
copyPaste: Additional options

If you set the copyPaste option to an object, you can set the following CopyPaste plugin options:

Option Possible settings Description
columnsLimit A number (default: Infinity) The maximum number of columns that can be copied
rowsLimit A number (default: Infinity) The maximum number of columns that can be copied
pasteMode 'overwrite' | 'shift_down' | 'shift_right' When pasting:
'overwrite': overwrite the currently-selected cells
'shift_down': move the currently-selected cells down
'shift_right': move the currently-selected cells to the right
copyColumnHeaders Boolean (default: false) true: add a context menu option for copying cells along with their nearest column headers
copyColumnGroupHeaders Boolean (default: false) true: add a context menu option for copying cells along with all their related columns headers
copyColumnHeadersOnly Boolean (default: false) true: add a context menu option for copying column headers nearest to the selected cells (without copying cells)
uiContainer An HTML element The UI container for the secondary focusable element

Read more:

Default: true
Example

// enable the plugin with the default configuration
copyPaste: true // set by default

// disable the plugin
copyPaste: false,

// enable the plugin with a custom configuration
copyPaste: {
  // set a maximum number of columns that can be copied
  columnsLimit: 25,

  // set a maximum number of rows that can be copied
  rowsLimit: 50,

  // set the paste behavior
  pasteMode: 'shift_down',

  // add the option to copy cells along with their nearest column headers
  copyColumnHeaders: true,

  // add the option to copy cells along with all their related columns headers
  copyColumnGroupHeaders: true,

  // add the option to copy just column headers (without copying cells)
  copyColumnHeadersOnly: true,

  // set a UI container
  uiContainer: document.body,
},

Members

columnsLimit

Source code

copyPaste.columnsLimit : number

The maximum number of columns than can be copied to the clipboard.

Default: Infinity

pasteMode

Source code

copyPaste.pasteMode : string

When pasting:

  • 'overwrite' - overwrite the currently-selected cells
  • 'shift_down' - move currently-selected cells down
  • 'shift_right' - move currently-selected cells to the right

Default: "overwrite"

rowsLimit

Source code

copyPaste.rowsLimit : number

The maximum number of rows than can be copied to the clipboard.

Default: Infinity

uiContainer

Source code

copyPaste.uiContainer : HTMLElement

The UI container for the secondary focusable element.

Methods

copy

Source code

copyPaste.copy([copyMode])

Copies the contents of the selected cells (and/or their related column headers) to the system clipboard.

Takes an optional parameter (copyMode) that defines the scope of copying:

copyMode value Description
'cells-only' (default) Copy the selected cells
'with-column-headers' - Copy the selected cells
- Copy the nearest column headers
'with-column-group-headers' - Copy the selected cells
- Copy all related columns headers
'column-headers-only' Copy the nearest column headers (without copying cells)
Param Type Default Description
[copyMode] string "cells-only" optional Copy mode.

copyCellsOnly

Source code

copyPaste.copyCellsOnly()

Copies the contents of the selected cells.

copyColumnHeadersOnly

Source code

copyPaste.copyColumnHeadersOnly()

Copies the contents of column headers that are nearest to the selected cells.

copyWithAllColumnHeaders

Source code

copyPaste.copyWithAllColumnHeaders()

Copies the contents of the selected cells and all their related column headers.

copyWithColumnHeaders

Source code

copyPaste.copyWithColumnHeaders()

Copies the contents of the selected cells and their nearest column headers.

cut

Source code

copyPaste.cut()

Cuts the contents of the selected cells to the system clipboard.

destroy

Source code

copyPaste.destroy()

Destroys the CopyPaste plugin instance.

disablePlugin

Source code

copyPaste.disablePlugin()

Disables the CopyPaste plugin for your Handsontable instance.

enablePlugin

Source code

copyPaste.enablePlugin()

Enables the CopyPaste plugin for your Handsontable instance.

getRangedCopyableData

Source code

copyPaste.getRangedCopyableData(ranges) ⇒ string

Converts the contents of multiple ranges (ranges) into a single string.

Param Type Description
ranges Array<{startRow: number, startCol: number, endRow: number, endCol: number}> Array of objects with properties startRow, endRow, startCol and endCol.

Returns: string - A string that will be copied to the clipboard.

getRangedData

Source code

copyPaste.getRangedData(ranges) ⇒ Array<Array>

Converts the contents of multiple ranges (ranges) into an array of arrays.

Param Type Description
ranges Array<{startRow: number, startCol: number, endRow: number, endCol: number}> Array of objects with properties startRow, startCol, endRow and endCol.

Returns: Array<Array> - An array of arrays that will be copied to the clipboard.

isEnabled

Source code

copyPaste.isEnabled() ⇒ boolean

Checks if the CopyPaste plugin is enabled.

This method gets called by Handsontable's beforeInit hook. If it returns true, the enablePlugin() method gets called.

paste

Source code

copyPaste.paste(pastableText, [pastableHtml])

Simulates the paste action.

For security reasons, modern browsers don't allow reading from the system clipboard.

Param Type Default Description
pastableText string The value to paste, as a raw string.
[pastableHtml] string "" optional The value to paste, as HTML.

setCopyableText

Source code

copyPaste.setCopyableText()

Prepares copyable text from the cells selection in the invisible textarea.

updatePlugin

Source code

copyPaste.updatePlugin()

Updates the state of the CopyPaste plugin.

Gets called when updateSettings() is invoked with any of the following configuration options: