react-datasheet

react-datasheet is no longer under active development. New maintainers are wanted. Please contact me if you wish to maintain this repo.

---

React-Datasheet

A simple react component to create a spreadsheet.

Demo here: https://nadbm.github.io/react-datasheet/

Examples are located in https://github.com/nadbm/react-datasheet/tree/master/docs/src/examples

Current features:

• Select cells, cut, copy and paste cells
• Navigation using keyboard keys
• Deletion using keyboard keys
• Callbacks for onCellsChanged, valueRenderer(visible data)
• dataRenderer(underlying data in the input, takes the value by default)
• Supply your own editors and view controls with custom renderers
• Extensive control over generated markup via custom renderers

Using Typescript? View Usage

Installation

Install from npm:

$ npm install react-datasheet --save

Import in your project:

import ReactDataSheet from 'react-datasheet';
// Be sure to include styles at some point, probably during your bootstrapping
import 'react-datasheet/lib/react-datasheet.css';

Usage

React-Datasheet generates a table with the cells. Double-clicking or typing edits the value and if changed, initiates an onCellsChanged callback. Pasting tabular data or deleting a range of cells also calls onCellsChanged.

The data provided should be an array of rows, and each row should include the cells.

Basic Usage

…

Cells with underlying data

There are two values that each cell shows. The first is via valueRenderer and the second is via dataRenderer. When a cell is in edit mode, it will show the value returned from dataRenderer. It needs to return a string as this value is set in an input field. Each of these callbacks are passed the cell value as well as the cell's coordinates in the spreadsheet. This allows you to apply formatting logic at rendering time, such as all cells in the third column should be formatted as dates.

const grid = [
   [{value:  5, expr: '1 + 4'}, {value:  6, expr: '6'}, {value: new Date('2008-04-10')}],
   [{value:  5, expr: '1 + 4'}, {value:  5, expr: '1 + 4'}, {value: new Date('2004-05-28')}]
]
const onCellsChanged = (changes) => changes.forEach(({cell, row, col, value}) => console.log("New expression :" + value))
<ReactDataSheet
  data={grid}
  valueRenderer={(cell, i, j) => j == 2 ? cell.value.toDateString() : cell.value}
  dataRenderer={(cell, i, j) => j == 2 ? cell.value.toISOString() : cell.expr}
  onCellsChanged={onCellsChanged}
/>

Cells with underlying component

const grid = [
  [{
    value:  5,
    component: (
      <button onClick={() => console.log("clicked")}>
        Rendered
      </button>
    )
  }]
]
<ReactDataSheet
  data={grid}
  valueRenderer={(cell) => cell.value}
/>

This renders a single cell with the value 5. Once in edit mode, the button will appear.

Cells with extra attributes

const grid = [
  [{value:  1, hint: 'Valid'}, {value:  3, hint: 'Not valid'}],
  [{value:  2}, {value:  4}]
]
<ReactDataSheet
  data={grid}
  valueRenderer={(cell) => cell.value}
  attributesRenderer={(cell) => (cell.hint ? { 'data-hint': cell.hint } : {})}
  ...
/>

This render 2 rows, each one with two cells, the cells in the first row will have an attribute data-hint and the other 2 will not.

Custom renderers

React-Datasheet allows you replace the renderers both for the overall structure (rows, cells, the sheet itself) as well as editors and viewers for individual cells. This allows you to radically refashion the sheet to suit your requirements.

For example, this shows how to add separate headers and a checkbox at the start of each row to control row "selected" state. It also specifies a custom view renderer and a custom editor for the first column of each row:

…

Note: For brevity, in this example the custom renderers are all defined as arrow functions inside of render, but using a bound function in the parent component or a separate custom component will let you avoid a lot of needless re-renders.

Options

Option	Type	Description
data	Array	Array of rows and each row should contain the cell objects to display
valueRenderer	func	Method to render the value of the cell function(cell, i, j). This is visible by default
dataRenderer	func	Method to render the underlying value of the cell function(cell, i, j). This data is visible once in edit mode.
overflow	'wrap'|'nowrap'|'clip'	Grid default for how to render overflow text in cells
onCellsChanged	func	onCellsChanged handler: function(arrayOfChanges[, arrayOfAdditions]) {}, where changes is an array of objects of the shape {cell, row, col, value}. See below for more details.
onContextMenu	func	Context menu handler : function(event, cell, i, j)
parsePaste	func	function (string) {} If set, the function will be called with the raw clipboard data. It should return an array of arrays of strings. This is useful for when the clipboard may have data with irregular field or line delimiters. If not set, rows will be split with line breaks and cells with tabs.
isCellNavigable	func	function (cell, row, col) {return true} If set, the function is used to determine whether navigation to the indicated cell should be allowed or not. If not then using cursor or tab navigation will skip over not allowed cells until it finds the next allowed cell.
handleCopy	func	function ({ event, dataRenderer, valueRenderer, data, start, end, range }) If set, this function is called whenever the user copies cells. The return string of this function is stored on the clipboard.

Advanced options

The following are optional functions or React Component that can completely override the native renderers of react datasheet. To know which props are passed down, see custom renderers

Option	Type	Description
sheetRenderer	func	Optional function or React Component to render the main sheet element. The default renders a table element.
rowRenderer	func	Optional function or React Component to render each row element. The default renders a tr element.
cellRenderer	func	Optional function or React Component to render each cell element. The default renders a td element.
valueViewer	func	Optional function or React Component to customize the way the value for each cell in the sheet is displayed. Affects every cell in the sheet. See cell options to override individual cells.
dataEditor	func	Optional function or React Component to render a custom editor. Affects every cell in the sheet. See cell options to override individual cells.
selected	object	Optional. Whether the selection is controlled or uncontrolled. Must be an object of this format: { start: { i: number, j; number }, end: { i: number, j: number } }, or null for no selection.
onSelect	func	Optional. function ({ start, end }) {} Triggered on every selection change. start and end have the same format as the selected prop.

onCellsChanged(arrayOfChanges[, arrayOfAdditions]) handler

React-DataSheet will call this callback whenever data in the grid changes:

• When the user enters a new value in a cell
• When the user hits the delete key with one or more selected cells
• When the user pastes tabular data into the table

The argument to the callback usually will be one array of objects with these properties:

Property	Type	Description
cell	object	the original cell object you provided in the data property. This may be null (see below)
row	number	row index of changed cell
col	number	column index of changed cell
value	any	The new cell value. This is usually a string, but a custom editor may provide any type of value.

If the change is the result of a user edit, the array will contain a single change object.