JavaScript Data Grid CopyPaste

In this article

• Description
• Options
  • copyPaste
• Members
  • columnsLimit
  • pasteMode
  • rowsLimit
  • uiContainer
• Methods
  • copy
  • copyCellsOnly
  • copyColumnHeadersOnly
  • copyWithAllColumnHeaders
  • copyWithColumnHeaders
  • cut
  • destroy
  • disablePlugin
  • enablePlugin
  • getRangedCopyableData
  • getRangedData
  • isEnabled
  • paste
  • setCopyableText
  • updatePlugin

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:

• The context menu.
• The keyboard shortcuts.
• The browser's menu bar.

Read more:

• Guides: Clipboard
• Configuration options: copyPaste

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 (opens new window)

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:

• Plugins: CopyPaste
• Guides: Clipboard

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 (opens new window)

copyPaste.columnsLimit : number

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

Default: Infinity

pasteMode

Source code (opens new window)

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 (opens new window)

copyPaste.rowsLimit : number

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

Default: Infinity

uiContainer

Source code (opens new window)

copyPaste.uiContainer : HTMLElement

The UI container for the secondary focusable element.

Methods

copy

Source code (opens new window)

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-all-column-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 (opens new window)

copyPaste.copyCellsOnly()

Copies the contents of the selected cells.

copyColumnHeadersOnly

Source code (opens new window)

copyPaste.copyColumnHeadersOnly()

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

copyWithAllColumnHeaders

Source code (opens new window)

copyPaste.copyWithAllColumnHeaders()

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

copyWithColumnHeaders

Source code (opens new window)

copyPaste.copyWithColumnHeaders()

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

cut

Source code (opens new window)

copyPaste.cut()

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

destroy

Source code (opens new window)

copyPaste.destroy()

Destroys the CopyPaste plugin instance.

disablePlugin

Source code (opens new window)

copyPaste.disablePlugin()

Disables the CopyPaste plugin for your Handsontable instance.

enablePlugin

Source code (opens new window)

copyPaste.enablePlugin()

Enables the CopyPaste plugin for your Handsontable instance.

getRangedCopyableData

Source code (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

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 (opens new window)

copyPaste.setCopyableText()

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

updatePlugin

Source code (opens new window)

copyPaste.updatePlugin()

Updates the state of the CopyPaste plugin.

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

• copyPaste
• fragmentSelection