lola-react-spreadsheet

This is the repository for the custom spreadsheet component that is used on Lola.com's budget edit screen. It was originally forked from react-data-grid and then heavily customized to the point where it made more sense to be a stand alone project. This package uses Typescript and Rollup for bundling. As of right now, it is not available as an npm package, but that may change in the future.

Getting Started

This package uses Storybook for development, creating a self-contained environment where you can test your changes before implementing them in the main application. It's easy to get started with development in a few steps:

1. $ git clone https://github.com/lolatravel/lola-react-spreadsheet.git
2. $ cd lola-react-spreadsheet
3. $ npm i
4. $ npm start

At this point, localhost:6006 should open up in your browser and you will be taken to the Storybook instance of the component.

There are only a couple stories at the time of writing. Feel free to add more stories if it would help your development process.

Basic Usage

import DataGrid from 'lola-react-spreadsheet';
import 'lola-react-spreadsheet/dist/react-data-grid.css';

const columns = [
  { key: 'id', name: 'ID' },
  { key: 'title', name: 'Title' }
];

const rows = [
  { id: 0, title: 'Example' },
  { id: 1, title: 'Demo' }
];

function App() {
  return (
    <DataGrid
      columns={columns}
      rows={rows}
    />
  );
}

API

DataGrid Props

columns (required)

type: arrayOf

Name	Type	Required	Description
name	string	true	The name of the column. This will be displayed in the header.
key	string	true	A unique key to distinguish each column
width	number/string	false	Column width. If not specified, will be determined automatically.
minWidth	number/string	false	The minimum width of a column.
maxWidth	number/string	false	The maximum width of a column.
formatter	Formatter	false	React component that renders the cell content.
editable	boolean	false	Whether the cells in this column are editable or not.
frozen	boolean	false	Whether this column is frozen or not. If true, column stays fixed while scrolling horizontally.
frozenAlignment	string	false	Which side frozen column should be pinned to. Defaults to left
editor	Editor	false	Editor component that is rendered when the cell is being edited.
formatValue	function	false	Formatter function to handle formatting while typing (eg. currency)

enableOptionsCol

type: boolean

Lets the spreadsheet know that there will be a column at the end of the table that will be fixed to the right side. This is useful if you want a column to hold actions that you might want to be visible at all times.

Usage:

<DataGrid
    enableOptionsCol
    columns={[
        ...
        { key: 'options', name: '', frozenAlignment: 'right', width: 54, frozen: true, editable: false }
    ]}
/>

expandRow

type: function

Used to expand and collapse nested rows. Only called if a row has children. Requires a function that takes the current row as a parameter. Currently only called when clicking on a cell in a column with key: 'name'. This should be updated at some point to be more agnostic.

Usage:

<DataGrid
    expandRow={row => { someHandlerFunc(row.id) }}
/>

headerRowHeight

type: number

The height of the header row in px.

Usage:

<DataGrid
    headerRowHeight={48}
/>

onFill

type: function

Function called whenever cells are filled. Can be used to create a custom callback.

onPaste

type: function

Function called whenever a value is pasted into a cell. Can be used to create a custom callback.

onRowsChange

type: function

Function that is called after any change is made to the spreadsheet.

rowHeight

type: number

The height of each row in px.

Usage:

<DataGrid
    rowHeight={60}
/>

rowKeyGetter

type: function

Custom function that is used to return the key of a row. In most cases, this can simply be: rowKeyGetter={row => row.id}

rows (required)

type: arrayOf

Each Row is an object with keys that correspond to the key item of a Column. There are a few other useful properties that can be used for formatting. In addition, any other properties can be added that might be wanted in a callback function.

Name	Type	Required	Description
id	string	Technically false, but recommended.	Unique id to identify each row
parentId	Column	false unless nested row.	Id of row under which this row is nested.
children	rows	false unless has nested rows.	Array of rows that are nested under this row.
isExpanded	boolean	false	Whether or not this row's children are displayed.
[column.key]	Row	false	Information for displaying cell contents based on the column.

Advanced Column Props

Editor

type: JSX Element

editor: props => <Editor { ...props } />

Name	Type	Description
rowIdx	number	The row index of the cell that is being edited.
column	Column	Reference to the current column.
top	number	Top positioning of cell in px.
left	number	Left positioning of cell in px.

Formatter

type: JSX Element

formatter: props => <Formatter { ...props } />

Name	Type	Description
rowIdx	number	The row index of the cell that is being rendered.
cell	Cell	Reference to the current cell.
row	Row	Reference to the row which contains this cell.
isCellSelected	boolean	Whether this cell is selected or not.

Row Types

Row

type: string/object

Name	Type	Required	Description
value	string	true	Value of text inside cell.
disabled	boolean	false	If true, cell cannot be edited
error	boolean	false	If true, cell text will be red to indicate something is wrong
alert	string	false	If string exists, cell will have a red background and tooltip that displays the alert string.
warning	string	false	If string exists, cell will have a yellow background and tooltip that displays the alert string.