Repository files navigation

A simple react component to create a spreadsheet.

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

Examples are located inhttps://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

Install from npm:

$ npm install react-datasheet --save

Import in your project:

importReactDataSheetfrom'react-datasheet';// Be sure to include styles at some point, probably during your bootstrappingimport'react-datasheet/lib/react-datasheet.css';

React-Datasheet generates a table with the cells. Double-clicking or typingedits the value and if changed, initiates anonCellsChanged callback. Pastingtabular data or deleting a range of cells also callsonCellsChanged.

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

classAppextendsReact.Component{constructor(props){super(props);this.state={grid:[[{value:1},{value:3}],[{value:2},{value:4}],],};}render(){return(<ReactDataSheetdata={this.state.grid}valueRenderer={cell=>cell.value}onCellsChanged={changes=>{constgrid=this.state.grid.map(row=>[...row]);changes.forEach(({ cell, row, col, value})=>{grid[row][col]={ ...grid[row][col], value};});this.setState({ grid});}}/>);}}

There are two values that each cell shows. The first is viavalueRenderer andthe second is viadataRenderer. When a cell is inedit mode, it will showthe value returned fromdataRenderer. It needs to return a string as thisvalue is set in an input field. Each of these callbacks are passed the cellvalue as well as the cell's coordinates in the spreadsheet. This allows you toapply formatting logic at rendering time, such asall cells in the third columnshould be formatted as dates.

constgrid=[[{value:5,expr:'1 + 4'},{value:6,expr:'6'},{value:newDate('2008-04-10')}],[{value:5,expr:'1 + 4'},{value:5,expr:'1 + 4'},{value:newDate('2004-05-28')}]]constonCellsChanged=(changes)=>changes.forEach(({cell, row, col, value})=>console.log("New expression :"+value))<ReactDataSheetdata={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}/>

constgrid=[[{value:5,component:(<buttononClick={()=>console.log("clicked")}>        Rendered</button>)}]]<ReactDataSheetdata={grid}valueRenderer={(cell)=>cell.value}/>

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

constgrid=[[{value:1,hint:'Valid'},{value:3,hint:'Not valid'}],[{value:2},{value:4}]]<ReactDataSheetdata={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 willhave an attribute data-hint and the other 2 will not.

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

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

constcolumns=getColumnsFromSomewhere()constisSelected=yourSelectionFunctionconstselectHandler=yourCallbackFunction<ReactDataSheetdata={grid}valueRenderer={(cell)=>cell.value}sheetRenderer={props=>(<tableclassName={props.className+' my-awesome-extra-class'}><thead><tr><thclassName='action-cell'/>{columns.map(col=>(<th>{col.name}</th>))}</tr></thead><tbody>{props.children}</tbody></table>)}rowRenderer={props=>(<tr><tdclassName='action-cell'><inputtype='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 asarrow functions inside of render, but using abound function in the parentcomponent or a separate custom component will let you avoid a lot of needlessre-renders.

The following are optional functions or React Component that can completelyoverride the native renderers of react datasheet. To know which props are passeddown, seecustom renderers

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 onearray of objects with theseproperties:

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

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

• There is nocell property
• eitherrow orcol, or both, will be outside the bounds of your originalgrid. They will correspond to the indices the new data would occupy if youexpanded your grid to hold them.

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

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

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

Each of the following custom renderers should be either a React Component or afunction that takes aprops argument and returns a react element (a.k.astateless functional component). React-DataSheet will supply certain propertiesto each renderer.

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

Except forvalueViewer anddataEditor, each custom renderer will receivereact's regularprops.children. Be sure to render{props.children} in yourcustom renderer.

ThesheetRenderer is responsible for laying out the sheet's main parentcomponent. By default, React-DataSheet uses atable element. React-DataSheetwill supply these properties:

TherowRenderer lays out each row in the sheet. By default, React-DataSheetuses atr element. React-DataSheet will supply these properties:

ThecellRenderer creates the container for each cell in the sheet. The defaultrenders atd element. React-DataSheet will supply these properties:

ThevalueViewer displays your cell's data with a custom component when in viewmode. For example, you might show a "three star rating" component instead thenumber 3. You can specify avalueViewer for the entire sheet and/or for anindividual cell.

React-DataSheet will supply these properties:

ThedataEditor displays your cell's data when in edit mode. You can can useany component you want, as long as you hook up the event handlers thatconstitute the contract between React-DataSheet and your editor. You can specifyadataEditor for the entire sheet and/or for an individual cell.