CopyPaste

Plugin: CopyPaste

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

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,
},

parsePastedValue

Source code

copyPaste.parsePastedValue : boolean

The parsePastedValue option determines how pasted content is written to cells when the user pastes from the clipboard into Handsontable (e.g. from another Handsontable instance or between cells in the same table). It does not affect how other applications read or process the clipboard.

When set to false, pasted content is written as plain strings. Non-scalar values (e.g. objects) are coerced to string, so an object becomes "[object Object]".

When set to true, pasted text is parsed so that JSON-like (or other supported) values are converted to JavaScript values and written to the data source. This allows copying and pasting more sophisticated JavaScript structures (e.g. objects, arrays) between cells and between Handsontable instances. Cells then store the resulting object (e.g. { id: 1, value: 'A1' }). Schema validation is relaxed so object-based values can be pasted into cells that would normally expect a scalar.

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

Setting	Description
false (default)	Write pasted content as plain strings
true	Parse pasted text and write JavaScript values

Default: false
Since: 17.0.0
Example

// write pasted content as strings (objects become "[object Object]")
parsePastedValue: false,

Example

// parse pasted text so cells receive JavaScript objects when pasted content is object-like
parsePastedValue: true,

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, [useSourceData]) ⇒ Array<Array>

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

Param	Type	Default	Description
ranges	Array<{startRow: number, startCol: number, endRow: number, endCol: number}>		Array of objects with properties startRow, startCol, endRow and endCol.
[useSourceData]	boolean	false	optional Whether to use the source data instead of the data. This will stringify objects as JSON.

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:

• copyPaste
• fragmentSelection