Events

The JSS data grid offers a range of custom events that allow for greater customization of applications. These events can be used in different ways, such as:

The global event dispatcher method;
Implementing methods for individual events such as onchange, onclick, etc.;
Implementing the onevent method inside a spreadsheet plugin.

In this section, we provide more details about the first two methods. If you are interested in the events inside plugins, please visit the plugin's documentation.

Documentation

Specific event handlers

There are several specific event handlers available in Jspreadsheet as shown below:

Event	description
onload	This method is called when the data in the spreadsheet is ready. `onload(spreadsheet: Object) => void`
onclick	When the spreadsheet is clicked. Sections: nested \| header \| row \| cell \| select-all \| tabs \| cloning \| toolbar \| footer `onclick(worksheet: Object, section: String, x: Number, y: Number, event: Object) => void`
onundo	When undo is applied `onundo(worksheet: Object, historyRecord: Object) => void`
onredo	When redo is applied `onredo(worksheet: Object, historyRecord: Object) => void`
onbeforesave	Before any data is sent to the backend. Can be used to overwrite the data or to cancel the action when return false. `onbeforesave(spreadsheet: Object, worksheet: Object, data: Object) => Boolean \| Object`
onsave	After the data is sent to the server. `onsave(spreadsheet: Object, worksheet: Object, data: Object) => void`
onerror	When a new error happens. `onerror(spreadsheet: Object, result: Object) => void`
onbeforechange	Before a column value is changed. It is possible to overwrite the original value, by returning a new value. `onbeforechange(worksheet: Object, cell: DOMElement, x: Number, y: Number, value: Any) => Boolean \| Any`
onchange	After a column value is changed. `onchange(worksheet: Object, cell: DOMElement, x: Number, y: Number, newValue: Any, oldValue: Any) => void`
onafterchanges	After all changes are applied in the table. `onafterchanges(worksheet: Object, records: Array)`
oncopy	When a copy is performed in the spreadsheet. Any string returned will overwrite the user data or return null to progress with the default behavior. `oncopy(worksheet: Object, selectedCells: Number[], data: String, cut: Boolean) => String`
onbeforepaste	Before the paste action is performed. Can return parsed or filtered data, can cancel the action when return false. `onbeforepaste(worksheet: Object, data: Array, x: Number, y: Number, properties: Object[]) => boolean \| Array`
onpaste	After a paste action is performed in the spreadsheet. `onpaste(worksheet: Object, data: Array) => void`
onbeforeinsertrow	Before a new row is inserted. Return false to cancel the user action. `onbeforeinsertrow(worksheet: Object, rows: Object[]) => Boolean \| Object[] \| void`
oninsertrow	After a new row is inserted. `oninsertrow(worksheet: Object, rows: Object[]) => void`
onbeforedeleterow	Before a row is deleted. Return false to cancel the user action. `onbeforedeleterow(worksheet: Object, rows: Number[]) => Number[] \| Boolean \| void`
ondeleterow	After a row is deleted. `ondeleterow(worksheet: Object, rows: Number[]) => void`
onbeforeinsertcolumn	Before a new column is inserted. Return false to cancel the user action. `onbeforeinsertcolumn(worksheet: Object, columns: Object[]) => Boolean \| Object[] \| void`
oninsertcolumn	After a new column is inserted. `oninsertcolumn(worksheet: Object, column: Object[]) => void`
onbeforedeletecolumn	Before a column is excluded. Return false to cancel the user action. `onbeforedeletecolumn(worksheet: Object, cols: Number[]) => boolean \| Number[] \| void`
ondeletecolumn	After a column is excluded. `ondeletecolumn(worksheet: Object, cols: Number[]) => void`
onmoverow	After a row is moved to a new position. `onmoverow(worksheet: Object, origin: Number, destination: Number, quantity: Number) => void;`
onmovecolumn	After a column is moved to a new position. `onmovecolumn(worksheet: Object, origin: Number, destination: Number, quantity: Number) => void`
onresizerow	After a height change for one or more rows. `onresizerow(worksheet: Object, row: Mixed, height: Mixed, oldHeight: Mixed) => void`
onresizecolumn	After a column width change for one or more columns. `onresizecolumn(worksheet: Object, column: Mixed, width: Mixed, oldWidth: Mixed) => void`
onbeforeselection	Before a selection happens. `onbeforeselection(worksheet: Object, px: Number, py: Number, ux: Number, uy: Number, origin?: Object) => void`
onselection	When the selection is changed. `onselection(worksheet: Object, px: Number, py: Number, ux: Number, uy: Number, origin?: Object) => void`
onbeforecomments	Before a new comment is added or updated. Return false to cancel the event. `onbeforecomments(worksheet: Object, newValues: Object) => Boolean \| void`
oncomments	After a new comment is added or updated. `oncomments(worksheet: Object, cells: Object, oldValues: Object) => void`
onbeforesort	It runs before sorting a column. It should return an array with a custom sorting or false to cancel the user action. `onbeforesort(worksheet: Object, column: Number, direction: Number, newOrderValues: Array) => Any`
onsort	When a column is sorted. `onsort(worksheet: Object, column: Number, direction: Number, newOrderValues: Array) => void`
onfocus	When the spreadsheet gets the focus. `onfocus(worksheet: Object) => void`
onblur	When the spreadsheet loses the focus. `onblur(worksheet: Object) => void`
onmerge	When merge cells is executed. `onmerge(worksheet: Object, newValue: Object, oldValue: Object) => void`
onchangeheader	When the header title is changed. `onchangeheader(worksheet: Object, column: Number, newValue: String, oldValue: String) => void`
onchangefooter	When the footers are created or updated. `onchangefooter(worksheet: Object, newValue: [], oldValue: []) => void`
onchangefootervalue	When the value in a cell footer is changed. `onchangefootervalue(worksheet: Object, x: Number, y: Number, value: String) => void`
onchangenested	When updating the nested headers `onchangenested(worksheet: Object, options: object) => void`
onchangenestedcell	When updating a nested cell `onchangenestedcell(worksheet: Object, x: Number, y: Number, properties: Object) => void`
oncreateeditor	When an editor is created. `oncreateeditor(worksheet: Object, cell: DOMElement, x: Number, y: Number, element: DOMElement, options: Object) => void`
oneditionstart	When the edition starts. `oneditionstart(worksheet: Object, cell: DOMElement, x: Number, y: Number) => void \| boolean`
oneditionend	When the edition ends. `oneditionend(worksheet: Object, cell: DOMElement, x: Number, y: Number, newValue: Any, save: Boolean) => void`
onchangestyle	When the style of a cell is changed. `onchangestyle(worksheet: Object, newValue: Object, oldValue: Object) => void`
onchangemeta	When cell meta information is added or updated. `onchangemeta(worksheet: Object, newValue: Object) => void`
onbeforechangepage	Before the page is changed. Can cancel the action by returning false. `onbeforechangepage(worksheet: Object, pageNumber: Number, oldPage: Number, quantityPerPage: Number) => Boolean \| void`
onchangepage	When pagination is enabled and the user changes the page. `onchangepage(worksheet: Object, pageNumber: Number, oldPageNumber: Number, quantityPerPage: Number) => void`
onbeforecreateworksheet	Add or change the options for a new worksheet. `onbeforecreateworksheet(worksheetOptions: Object, position: Number) => boolean \| Any`
oncreateworksheet	When the user creates a new worksheet. `oncreateworksheet(worksheet: Object, worksheetOptions: Object, position: Number) => void`
onrenameworksheet	When the user renames a worksheet. `onrenameworksheet(worksheet: Object, position: Number, newValue: String, oldValue: String) => void`
ondeleteworksheet	When the user deletes a worksheet. `ondeleteworksheet(worksheet: Object, position: Number) => void`
onmoveworksheet	When the user updates the worksheet tab position. `onmoveworksheet(worksheet: Object, from: Number, to: Number) => void`
onopenworksheet	When the user opens a worksheet. `onopenworksheet(worksheet: Object, worksheet: Number) => void`
onchangerowid	When there is a row id update. `onchangerowid(worksheet: Object, rows: Array) => void`
onbeforefilter	Action to be executed before filtering rows. It can cancel the action by returning false. `onbeforefilter(worksheet: Object, filters: Array, data: Array) => void`
onfilter	After the filter has been applied to the rows. `onfilter(worksheet: Object, filters: Array, data: Array) => void`
oncreatecell	When a new cell is created. `oncreatecell(worksheet: Object, element: HTMLElement, x: Number, y: Number, value: String) => void`
oncreaterow	After a new row is inserted. `oncreaterow(worksheet: Object, rowNumber: Number, tr: HTMLElement) => void`
onbeforeformula	Before executing a formula. `onbeforeformula(worksheet: Object, expression: String, x: Number, y: Number) => void \| string \| boolean`
onformulachain	Get the information about the expressions executed from the formula chain. `onformulachain(worksheet: Object, expressions: Array) => void`
onopenfilter	Customize the items available when the filter editor is open. `onopenfilter(worksheet: Object, column: number, options: Array) => options \| void`
onresize	Viewport dimensions has changed. `onresize(worksheet: Object, w: number, h: number) => void`
onchangedefinednames	When definedNames is updated. `onchangedefinednames(worksheet: Object, data: []) => void`
oninput	New char is entered on editor. `oninput(worksheet: Object, event: Object) => void`
onchangerowvisibility	When the visibility of rows changes. `onchangerowvisibility(worksheet: Object, state: boolean: affected: []]) => void`
onchangecolumnvisibility	When the visibility of cols changes. `onchangecolumnvisibility(worksheet: Object, state: boolean: affected: []]) => void`
onsearchstart	It happens before all the search events. `onsearchstart(worksheet: Object, terms: String)`
onsearchrow	It helps to customize the searching process. `onsearchrow(worksheet: Object, rowNumber: number, terms: String)`
onbeforesearch	Action to be executed before the search. It can be used to cancel or to intercept and customize the search process. `onbeforesearch(worksheet: Object, terms: String, results: Array, search: Object)`
onsearch	After the search process is completed. `onsearch(worksheet: Object, terms: String, rowNumber: Array, search: Object)`
oncreatecolumn	When a new column is created. `oncreatecolumn(worksheet: Object, columnNumber: number, td: HTMLElement, options: Object)`
oncreaterow	After a new row is inserted. `oncreaterow(worksheet: Object, rowNumber: Number, tr: HTMLElement)`
ongrouprow	When the user creates a group of rows `oncreaterowgroup?: (worksheet: object, row: number, elements: number\|undefined) => void`
onopenrowgroup	When the user opens a group of rows `onopenrowgroup?: (worksheet: object, row: number) => void`
oncloserowgroup	When the user closes a group of rows `oncloserowgroup?: (worksheet: object, row: number) => void`
ongroupcolumn	When the user creates a group of columns `oncreatecolumngroup?: (worksheet: Object, column: Number, elements: Number\|undefined) => void`
onopencolumngroup	When the user opens a group of columns `onopencolumngroup?: (worksheet: Object, column: Number) => void`
onclosecolumngroup	When the user closes a group of columns `onclosecolumnroup?: (worksheet: object, Object: Number) => void`
onchangemedia	When a media object is added, removed or updated. `(worksheet: object, newValue: object[], oldValue: object, affectedRecords: object[]) => void`
onchangereferences	When there is a reference update. `onchangereferences?: (worksheet: object, affected: object, deletedTokens: string[], deletedColumns: string[], deletedRows: string[]) => void;`
onchangeproperty	Updates on cell properties via setProperty or updateProperty. `onchangeproperty(worksheet: Object, updates: Object[]) => void`
onchangeconfig	Fire when there is a change in the configuration. `getConfig(config: string, spreadsheetLevel?: boolean) => void`

Special events

Event	description
onevent	General method to handler any event. The number of arguments depends on each event. `onevent(eventName: String, worksheet: Object, a?: any, b?: any, c?: any, d?: any, e?: any, f?: any) => any`
contextmenu	Return false to cancel the contextMenu event, or return custom elements for the contextmenu. `contextMenu(worksheet: Object, x: Number, y: Number, e: Object, items: [], section: String, a1: Any, a2: Any) => []`

The global event handler

The onevent is a global and centralized method that handles all events. It's essential to note that the number of arguments required will depend on the specific event that has been triggered. NOTE: You can see events in the browser console.

<html>
<script src="https://jspreadsheet.com/v11/jspreadsheet.js"></script>
<script src="https://jsuites.net/v5/jsuites.js"></script>
<link rel="stylesheet" href="https://jspreadsheet.com/v11/jspreadsheet.css" type="text/css" />
<link rel="stylesheet" href="https://jsuites.net/v5/jsuites.css" type="text/css" />

<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Material+Icons" />

<div id='spreadsheet'></div>

<script>
// Set your JSS license key (The following key only works for one day)
jspreadsheet.setLicense('OWYwMGU3MDJkYjMwM2QzMWFlZDgwNGU2ZTcwZTQ4MzcwZjc1NGY4MmQzNjQ4Mjc0MzBkMDZiNDI3YzIyMjg4YzA1NGM1ZDBlNTZjMWFkM2YxMWRhY2FhMzhmN2Y3NGIwMjc0NjVlZWE0N2MyYzZiZGQ5ODUzMmQ4NmI2YTNjMWQsZXlKamJHbGxiblJKWkNJNklpSXNJbTVoYldVaU9pSktjM0J5WldGa2MyaGxaWFFpTENKa1lYUmxJam94TnpNeU1qWTJPRGt5TENKa2IyMWhhVzRpT2xzaWFuTndjbVZoWkhOb1pXVjBMbU52YlNJc0ltTnZaR1Z6WVc1a1ltOTRMbWx2SWl3aWFuTm9aV3hzTG01bGRDSXNJbU56WWk1aGNIQWlMQ0ozWldJaUxDSnNiMk5oYkdodmMzUWlYU3dpY0d4aGJpSTZJak0wSWl3aWMyTnZjR1VpT2xzaWRqY2lMQ0oyT0NJc0luWTVJaXdpZGpFd0lpd2lkakV4SWl3aVkyaGhjblJ6SWl3aVptOXliWE1pTENKbWIzSnRkV3hoSWl3aWNHRnljMlZ5SWl3aWNtVnVaR1Z5SWl3aVkyOXRiV1Z1ZEhNaUxDSnBiWEJ2Y25SbGNpSXNJbUpoY2lJc0luWmhiR2xrWVhScGIyNXpJaXdpYzJWaGNtTm9JaXdpY0hKcGJuUWlMQ0p6YUdWbGRITWlMQ0pqYkdsbGJuUWlMQ0p6WlhKMlpYSWlMQ0p6YUdGd1pYTWlYU3dpWkdWdGJ5STZkSEoxWlgwPQ==');

// Create a new spreadsheet
jspreadsheet(document.getElementById('spreadsheet'), {
    worksheets: [{
        data: [
            ['Mazda', 2001, 2000],
            ['Peugeot', 2010, 5000],
            ['Honda Fit', 2009, 3000],
            ['Honda CRV', 2010, 6000],
        ],
        columns:[
            { title:'Model', width:'300px' },
            { title:'Year', width:'80px' },
            { title:'Price', width:'100px' },
        ],
    }],
    onevent: function(eventName,worksheet,a,b,c,d,e,f) {
        console.log(eventName,worksheet,a,b,c,d,e,f);
    }
});
</script>
</html>

import React, { useRef } from "react";
import { Spreadsheet, Worksheet } from "@jspreadsheet/react";
import "jsuites/dist/jsuites.css";
import "jspreadsheet/dist/jspreadsheet.css";

const license = 'OWYwMGU3MDJkYjMwM2QzMWFlZDgwNGU2ZTcwZTQ4MzcwZjc1NGY4MmQzNjQ4Mjc0MzBkMDZiNDI3YzIyMjg4YzA1NGM1ZDBlNTZjMWFkM2YxMWRhY2FhMzhmN2Y3NGIwMjc0NjVlZWE0N2MyYzZiZGQ5ODUzMmQ4NmI2YTNjMWQsZXlKamJHbGxiblJKWkNJNklpSXNJbTVoYldVaU9pSktjM0J5WldGa2MyaGxaWFFpTENKa1lYUmxJam94TnpNeU1qWTJPRGt5TENKa2IyMWhhVzRpT2xzaWFuTndjbVZoWkhOb1pXVjBMbU52YlNJc0ltTnZaR1Z6WVc1a1ltOTRMbWx2SWl3aWFuTm9aV3hzTG01bGRDSXNJbU56WWk1aGNIQWlMQ0ozWldJaUxDSnNiMk5oYkdodmMzUWlYU3dpY0d4aGJpSTZJak0wSWl3aWMyTnZjR1VpT2xzaWRqY2lMQ0oyT0NJc0luWTVJaXdpZGpFd0lpd2lkakV4SWl3aVkyaGhjblJ6SWl3aVptOXliWE1pTENKbWIzSnRkV3hoSWl3aWNHRnljMlZ5SWl3aWNtVnVaR1Z5SWl3aVkyOXRiV1Z1ZEhNaUxDSnBiWEJ2Y25SbGNpSXNJbUpoY2lJc0luWmhiR2xrWVhScGIyNXpJaXdpYzJWaGNtTm9JaXdpY0hKcGJuUWlMQ0p6YUdWbGRITWlMQ0pqYkdsbGJuUWlMQ0p6WlhKMlpYSWlMQ0p6YUdGd1pYTWlYU3dpWkdWdGJ5STZkSEoxWlgwPQ==';

export default function App() {
    // Spreadsheet array of worksheets
    const spreadsheet = useRef();
    // Data
    const data = [
        ['Mazda', 2001, 2000],
        ['Peugeot', 2010, 5000],
        ['Honda Fit', 2009, 3000],
        ['Honda CRV', 2010, 6000],
    ];
    const columns = [
        { title:'Model', width:'300px' },
        { title:'Year', width:'80px' },
        { title:'Price', width:'100px' },
    ];

    // Event handler
    const onevent = (eventName,worksheet,a,b,c,d,e,f) => {
        console.log(eventName,worksheet,a,b,c,d,e,f);
    };

    // Render data grid component
    return (
        <Spreadsheet ref={spreadsheet} license={license} onevent={onevent}>
            <Worksheet data={data} columns={columns} />
        </Spreadsheet>
    );
}

<template>
    <Spreadsheet ref="spreadsheet" :license="license" :onevent="onevent">
        <Worksheet :data="data" :columns="columns" />
    </Spreadsheet>
</template>

<script>
import { Spreadsheet, Worksheet } from "@jspreadsheet/vue";
import "jsuites/dist/jsuites.css";
import "jspreadsheet/dist/jspreadsheet.css";

const license = 'OWYwMGU3MDJkYjMwM2QzMWFlZDgwNGU2ZTcwZTQ4MzcwZjc1NGY4MmQzNjQ4Mjc0MzBkMDZiNDI3YzIyMjg4YzA1NGM1ZDBlNTZjMWFkM2YxMWRhY2FhMzhmN2Y3NGIwMjc0NjVlZWE0N2MyYzZiZGQ5ODUzMmQ4NmI2YTNjMWQsZXlKamJHbGxiblJKWkNJNklpSXNJbTVoYldVaU9pSktjM0J5WldGa2MyaGxaWFFpTENKa1lYUmxJam94TnpNeU1qWTJPRGt5TENKa2IyMWhhVzRpT2xzaWFuTndjbVZoWkhOb1pXVjBMbU52YlNJc0ltTnZaR1Z6WVc1a1ltOTRMbWx2SWl3aWFuTm9aV3hzTG01bGRDSXNJbU56WWk1aGNIQWlMQ0ozWldJaUxDSnNiMk5oYkdodmMzUWlYU3dpY0d4aGJpSTZJak0wSWl3aWMyTnZjR1VpT2xzaWRqY2lMQ0oyT0NJc0luWTVJaXdpZGpFd0lpd2lkakV4SWl3aVkyaGhjblJ6SWl3aVptOXliWE1pTENKbWIzSnRkV3hoSWl3aWNHRnljMlZ5SWl3aWNtVnVaR1Z5SWl3aVkyOXRiV1Z1ZEhNaUxDSnBiWEJ2Y25SbGNpSXNJbUpoY2lJc0luWmhiR2xrWVhScGIyNXpJaXdpYzJWaGNtTm9JaXdpY0hKcGJuUWlMQ0p6YUdWbGRITWlMQ0pqYkdsbGJuUWlMQ0p6WlhKMlpYSWlMQ0p6YUdGd1pYTWlYU3dpWkdWdGJ5STZkSEoxWlgwPQ==';

export default {
    components: {
        Spreadsheet,
        Worksheet,
    },
    methods: {
        // Event handler
        onevent (eventName,worksheet,a,b,c,d,e,f) {
            console.log(eventName,worksheet,a,b,c,d,e,f);
        };
    },
    data() {
        // Data
        const data = [
            ['Mazda', 2001, 2000],
            ['Peugeot', 2010, 5000],
            ['Honda Fit', 2009, 3000],
            ['Honda CRV', 2010, 6000],
        ];
        const columns = [
            { title:'Model', width:'300px' },
            { title:'Year', width:'80px' },
            { title:'Price', width:'100px' },
        ];

        return {
            data,
            columns,
            license,
        };
    }
}
</script>

import { Component, ViewChild, ElementRef } from "@angular/core";
import jspreadsheet from "jspreadsheet";

import "jspreadsheet/dist/jspreadsheet.css"
import "jsuites/dist/jsuites.css"

// Set your JSS license key (The following key only works for one day)
jspreadsheet.setLicense('OWYwMGU3MDJkYjMwM2QzMWFlZDgwNGU2ZTcwZTQ4MzcwZjc1NGY4MmQzNjQ4Mjc0MzBkMDZiNDI3YzIyMjg4YzA1NGM1ZDBlNTZjMWFkM2YxMWRhY2FhMzhmN2Y3NGIwMjc0NjVlZWE0N2MyYzZiZGQ5ODUzMmQ4NmI2YTNjMWQsZXlKamJHbGxiblJKWkNJNklpSXNJbTVoYldVaU9pSktjM0J5WldGa2MyaGxaWFFpTENKa1lYUmxJam94TnpNeU1qWTJPRGt5TENKa2IyMWhhVzRpT2xzaWFuTndjbVZoWkhOb1pXVjBMbU52YlNJc0ltTnZaR1Z6WVc1a1ltOTRMbWx2SWl3aWFuTm9aV3hzTG01bGRDSXNJbU56WWk1aGNIQWlMQ0ozWldJaUxDSnNiMk5oYkdodmMzUWlYU3dpY0d4aGJpSTZJak0wSWl3aWMyTnZjR1VpT2xzaWRqY2lMQ0oyT0NJc0luWTVJaXdpZGpFd0lpd2lkakV4SWl3aVkyaGhjblJ6SWl3aVptOXliWE1pTENKbWIzSnRkV3hoSWl3aWNHRnljMlZ5SWl3aWNtVnVaR1Z5SWl3aVkyOXRiV1Z1ZEhNaUxDSnBiWEJ2Y25SbGNpSXNJbUpoY2lJc0luWmhiR2xrWVhScGIyNXpJaXdpYzJWaGNtTm9JaXdpY0hKcGJuUWlMQ0p6YUdWbGRITWlMQ0pqYkdsbGJuUWlMQ0p6WlhKMlpYSWlMQ0p6YUdGd1pYTWlYU3dpWkdWdGJ5STZkSEoxWlgwPQ==');

@Component({
    standalone: true,
    selector: "app-root",
    template: `<div #spreadsheet></div>`
})
export class AppComponent {
    @ViewChild("spreadsheet") spreadsheet: ElementRef;
    // Worksheets
    worksheets: jspreadsheet.worksheetInstance[];
    // Create a new data grid
    ngAfterViewInit() {
        // Create spreadsheet
        this.worksheets = jspreadsheet(this.spreadsheet.nativeElement, {
            worksheets: [{
                data: [
                    ['Mazda', 2001, 2000],
                    ['Peugeot', 2010, 5000],
                    ['Honda Fit', 2009, 3000],
                    ['Honda CRV', 2010, 6000],
                ],
                columns:[
                    { title:'Model', width:'300px' },
                    { title:'Year', width:'80px' },
                    { title:'Price', width:'100px' },
                ],
            }],
            onevent: function(eventName,worksheet,a,b,c,d,e,f) {
                console.log(eventName,worksheet,a,b,c,d,e,f);
            }
        });
    }
}

Edit this page on GitHub