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

class App extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      grid: [
        [{ value: 1 }, { value: 3 }],
        [{ value: 2 }, { value: 4 }],
      ],
    };
  }
  render() {
    return (
      <ReactDataSheet
        data={this.state.grid}
        valueRenderer={cell => cell.value}
        onCellsChanged={changes => {
          const grid = this.state.grid.map(row => [...row]);
          changes.forEach(({ cell, row, col, value }) => {
            grid[row][col] = { ...grid[row][col], value };
          });
          this.setState({ grid });
        }}
      />
    );
  }
}

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:

const columns = getColumnsFromSomewhere()
const isSelected = yourSelectionFunction
const selectHandler = yourCallbackFunction

<ReactDataSheet
  data={grid}
  valueRenderer={(cell) => cell.value}
  sheetRenderer={props => (
    <table className={props.className + ' my-awesome-extra-class'}>
        <thead>
            <tr>
                <th className='action-cell' />
                {columns.map(col => (<th>{col.name}</th>))}
            </tr>
        </thead>
        <tbody>
            {props.children}
        </tbody>
    </table>
  )}
  rowRenderer={props => (
    <tr>
        <td className='action-cell'>
            <input
                type='checkbox'
                checked={isSelected(props.row)}
                onChange={selectHandler}
            />
        </td>
        {props.children}
    </tr>
  )}
  valueViewer={MyViewComponent}
  dataEditor={props => (
    props.col === 0 ? <MyDatePicker {...props} /> : <DataEditor {...props}/>
  )}
  ...
/>

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

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

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:

If the change is the result of a user edit, the array will contain a single change object. If the user pastes data or deletes a range of cells, the array will contain an element for each affected cell.

Additions: If the user pastes data that extends beyond the bounds of the grid (for example, pasting two-row-high data on the last line), there will be a second argument to the handler containing an array of objects that represent the out-of-bounds data. These object will have the same properties, except:

• There is no cell property
• either row or col, or both, will be outside the bounds of your original grid. They will correspond to the indices the new data would occupy if you expanded your grid to hold them.

You can choose to ignore the additions, or you can expand your model to accommodate the new data.

Deprecated handlers

Previously React-DataSheet supported two change handlers. These are still supported for backwards compatibility, but will be removed at some point in the future.

Cell Options

The cell object is what gets passed back to the onChange callback. They can contain the following options as well

Custom Renderers

Each of the following custom renderers should be either a React Component or a function that takes a props argument and returns a react element (a.k.a stateless functional component). React-DataSheet will supply certain properties to each renderer.

In some cases React-DataSheet will include event handlers as properties to your custom renderer. You must hook up these handlers to your component or aspects of React-DataSheet's built-in behavior will cease to work.

Except for valueViewer and dataEditor, each custom renderer will receive react's regular props.children. Be sure to render {props.children} in your custom renderer.

Sheet Renderer

The sheetRenderer is responsible for laying out the sheet's main parent component. By default, React-DataSheet uses a table element. React-DataSheet will supply these properties:

Row Renderer

The rowRenderer lays out each row in the sheet. By default, React-DataSheet uses a tr element. React-DataSheet will supply these properties:

Cell Renderer

The cellRenderer creates the container for each cell in the sheet. The default renders a td element. React-DataSheet will supply these properties:

Value Viewer

The valueViewer displays your cell's data with a custom component when in view mode. For example, you might show a "three star rating" component instead the number 3. You can specify a valueViewer for the entire sheet and/or for an individual cell.

React-DataSheet will supply these properties:

Data Editor

The dataEditor displays your cell's data when in edit mode. You can can use any component you want, as long as you hook up the event handlers that constitute the contract between React-DataSheet and your editor. You can specify a dataEditor for the entire sheet and/or for an individual cell.