@nadavshaar/react-grid-table v1.1.2

react-grid-table

A modular table, based on a CSS grid layout, optimized for fast configuration and deep customization.

Supported features:

• Async support
• Sort by column
• Column resize
• Column reorder
• Search with highlight
• Pagination
• Row selection
• Inline row editing
• Column pinning (pre-configured)
• Column visibility management
• Virtual scroll
• Sticky header
• Dynamic row height

Live Demo

Install

npm i @nadavshaar/react-grid-table

Usage

By default, the table is fully featured even with just a basic configuration of rows and columns.

Example:

import React from "react";
import GridTable from '@nadavshaar/react-grid-table';

// custom cell component
const Username = ({ tableManager, value, field, data, column, colIndex, rowIndex }) => {
    return (
        <div className='rgt-cell-inner' style={{display: 'flex', alignItems: 'center', overflow: 'hidden'}}>
            <img src={data.avatar} alt="user avatar" />
            <span className='rgt-text-truncate' style={{marginLeft: 10}}>{value}</span>
        </div>
    )
}

const rows = [
    { 
        "id": 1, 
        "username": "wotham0", 
        "gender": "Male", 
        "last_visited": "12/08/2019", 
        "test": {"x": 1, "y": 2}, 
        "avatar":"https://robohash.org/atquenihillaboriosam.bmp?size=32x32&set=set1"
    },
    { 
        "id": 2, 
        "username": "dbraddon2", 
        "gender": "Female", 
        "last_visited": "16/07/2018", 
        "test": {"x": 3, "y": 4}, 
        "avatar":"https://robohash.org/etsedex.bmp?size=32x32&set=set1"
    },
    { 
        "id": 3, 
        "username": "dridett3", 
        "gender": "Male", 
        "last_visited": "20/11/2016", 
        "test": {"x": 5, "y": 8}, 
        "avatar":"https://robohash.org/inimpeditquam.bmp?size=32x32&set=set1"
    },
    { 
        "id": 4, 
        "username": "gdefty6", 
        "gender": "Female", 
        "last_visited": "03/08/2019", 
        "test": {"x": 7, "y": 4}, 
        "avatar":"https://robohash.org/nobisducimussaepe.bmp?size=32x32&set=set1"
    },
    { 
        "id": 5, 
        "username": "hbeyer9", 
        "gender": "Male", 
        "last_visited": "10/10/2016", 
        "test": {"x": 2, "y": 2}, 
        "avatar":"https://robohash.org/etconsequatureaque.jpg?size=32x32&set=set1"
    }
];

const columns = [
    {
        id: 1, 
        field: 'username', 
        label: 'Username',
        cellRenderer: Username,
    }, 
    {
        id: 2, 
        field: 'gender', 
        label: 'Gender',
    },
    {
        id: 3, 
        field: 'last_visited', 
        label: 'Last Visited',
        sort: ({ a, b, isAscending }) => {
            let aa = a.split('/').reverse().join(),
            bb = b.split('/').reverse().join();
            return aa < bb ? isAscending ? -1 : 1 : (aa > bb ? isAscending ? 1 : -1 : 0);
        }
    },
    {
        id: 4, 
        field: 'test', 
        label: 'Score',
        getValue: ({ value }) => value.x + value.y
    }
];

const MyAwesomeTable = () => <GridTable columns={columns} rows={rows} />;

export default MyAwesomeTable;

Docs

Table of contents

• Main components
• Props
• Configuration props
• Event props
• Async props
• The columns prop
• The checkbox column
• The rows prop
• The components prop
• The additionalProps prop
• The tableManager API
• How-To: Sync/Async
• How-To: Row-Editing
• How-To: Styling

Support this package

Main components

HEADER (optional | customizable): search & column visibility management.

TABLE-HEADER: sort, resize & column reorder.

TABLE-BODY: displaying data / loader / no-results, row editing & row selection.

FOOTER (optional | customizable): rows information, rows per page & pagination.

Props

Configuration props

Event props

Async props

props - detailed

columns

Type: array of objects.

This prop defines the columns configuration.

Each column (except for 'checkbox' column) has support for the following properties:

Example:

// column config

{
  id: 'some-unique-id',
  field: 'first_name',
  label: 'First Name',
  className: '',
  pinned: false,
  width: '200px',
  getValue: ({ tableManager, value, column, rowData }) => value, 
  setValue: ({ value, data, setRow, column }) => { setRow({ ...data, [column.field]: value}) },
  minResizeWidth: 70,
  maxResizeWidth: null,
  sortable: true,
  editable: true,
  searchable: true,
  visible: true,
  resizable: true,
  search: ({value, searchText}) => { },
  sort: ({a, b, isAscending}) => { },
  cellRenderer: ({ tableManager, value, data, column, colIndex, rowIndex }) => ( children ),
  headerCellRenderer: ({ tableManager, column }) => ( children ),
  editorCellRenderer: ({ tableManager, value, data, column, colIndex, rowIndex, onChange }) => ( children ),
  placeHolderRenderer: ({ tableManager, value, data, column, colIndex, rowIndex }) => ( children )
}

checkbox-column

Rows selection is done by a predefined column, simply add a column with an id of 'checkbox'.

Checkbox column has support for the following properties:

Example:

// checkbox column config

{
  id: 'checkbox',
  pinned: true,
  className: '',
  width: '54px',
  minResizeWidth: 0,
  maxResizeWidth: null,
  resizable: false,
  visible: true,
  cellRenderer: ({tableManager, value, data, column, colIndex, rowIndex, onChange, disabled}) => ( children )
  headerCellRenderer: ({tableManager, column, mode, ref, checked, disabled, indeterminate, onChange}) => ( children )
}

rows

Type: array of objects.

This prop containes the data for the rows.

Each row should have a unique identifier field, which by default is id, but it can be changed to a different field using the rowIdField prop.

// Example for a single row data

{
  "id": "some-unique-id", 
  "objectValueField": {"x": 1, "y": 2}, 
  "username":"wotham0",
  "first_name":"Waldemar",
  "last_name":"Otham",
  "avatar":"https://robohash.org/atquenihillaboriosam.bmp?size=32x32&set=set1",
  "email":"wotham0@skyrock.com",
  "gender":"Male",
  "ip_address":"113.75.186.33",
  "last_visited":"12/08/2019"
}

Note: If a property value is not of type string, or in cases you don't specify a field for the column, you'll have to use the getValue function on the column in order to extract the desired value.

Signature: getValue: ({ tableManager, value, column, rowData }) => string

Example:

Let's say the field's value for a cell is an object:

{ ... , fullName: {firstName: 'some-first-name', lastName: 'some-last-name'} },

Its getValue function for displaying the first and last name as a full name, would be:

getValue: ({ value }) => value.firstName + ' ' + value.lastName

The returned value will be used for searching, sorting etc...

components

Type: object.

This prop gives you the ability to override the internal components with your own custom components.

All components are exported so you'll be able to import them from anywhere but you'll be responsible to supply them with their props:

Example: Overriding the header component

const Header = ({tableManager}) => {

    const { searchApi, columnsVisibilityApi, columnsApi } = tableManager;

    const { searchText, setSearchText } = searchApi;
    const { toggleColumnVisibility } = columnsVisibilityApi;
    const { columns } = columnsApi;

    return (
        <div style={{display: 'flex', flexDirection: 'column', padding: '10px 20px', background: '#fff', width: '100%'}}>
            <div>
                <label htmlFor="my-search" style={{fontWeight: 500, marginRight: 10}}>
                    Search for:
                </label>
                <input 
                    name="my-search"
                    type="search" 
                    value={searchText} 
                    onChange={e => setSearchText(e.target.value)} 
                    style={{width: 300}}
                />
            </div>
            <div style={{display: 'flex', marginTop: 10}}>
                <span style={{ marginRight: 10, fontWeight: 500 }}>Columns:</span>
                {
                    columns.map((column, idx) => (
                        <div key={idx} style={{flex: 1}}>
                            <input 
                                id={`checkbox-${idx}`}
                                type="checkbox" 
                                onChange={ e => toggleColumnVisibility(column.id) } 
                                checked={ column.visible !== false } 
                            />
                            <label htmlFor={`checkbox-${idx}`} style={{flex: 1, cursor: 'pointer'}}>
                                {column.label}
                            </label>
                        </div>
                    ))
                }
            </div>
        </div>
    )
}

const MyAwesomeTable = props => {
    ...
    return (
        <GridTable
            ...
            components={{ Header }}
        />
    )
}

additionalProps

Type: object.

This prop gives you the ability to pass props to internal components/modules.

Example Passing props to the cell component:

additionalProps={{ cell: { ... }, ... }}

List of components/modules you can pass props to:

• header
• search
• columnVisibility
• headerCell
• headerSelectionCell
• cell
• editorCell
• selectionCell
• placeHolderCell
• footer
• information
• pageSize
• pagination
• rowVirtualizer

tableManager

This is the API object used by the internal components, you can use it to do anything that the API provides, outside of the component.

API Structure:

• id: A unique identifier for each table component.
• isMounted: Is the table mounted.
• isInitialized: Is the table initialized. Will be set to true once all components are initialized.
• mode: 'sync' or 'async', derived from the supplied props.
• isLoading: Is the table currently loading data.
• config: All the params that defines the table's user-interface and its behavior.
• refs: ref objects for selected elements.
• columnsApi: API of the columns.
• columnsVisibilityApi: API of the columns visibility.
• searchApi: API of the search.
• sortApi: API of the sort.
• rowsApi: API of the rows
• paginationApi: API of the pagination.
• rowSelectionApi: API of the rows selection.
• rowEditApi: API of the row editing.
• rowVirtualizer: API of the rows virtualizer (See full documentation at react-virtual).
• asyncApi: API of the async functionality.

config

refs

columnsApi

columnsVisibilityApi

searchApi

sortApi

rowsApi

paginationApi

rowSelectionApi

rowEditApi

asyncApi

How to...

Sync/Async

react-grid-table supports 4 different data models:

Sync:

Use this flow if you have all the data locally.
Just pass all the data using the rows prop.

Required props:

Example:

export const SyncedTable = () => {

    const rows = getRows();
    const columns = getColumns();

    return (
        <GridTable
            columns={columns}
            rows={rows}
        />
    )
}

Async (Uncontrolled):

Use this flow if you need to fetch your data asynchrony, and want react-grid-table to manage it internally.
All the data is supplied to the table via the onRowsRequest prop.

Required props:

Example:

export const AsyncUncontrolledTable = () => {
    
    const columns = getColumns();

    const onRowsRequest = async (requestData, tableManager) => {
        const response = await fetch(`app/api/rows`, {
            method: 'post',
            body: {
                from: requestData.from,
                to: requestData.to,
                searchText: requestData.searchText,
                sort: requestData.sort,
            },
        }).then(response => response.json()).catch(console.warn);

        if(!response?.items) return;
        
        return {
            rows: response.items,
            totalRows: response.totalItems
        };
    }

    return (
        <GridTable
            columns={columns}
            onRowsRequest={onRowsRequest}
        />
    )
}

Async (Controlled):

Use this flow if you need to fetch your data asynchrony, and want react-grid-table to manage it internally, but still be able to use it in other places in the app.
All the data is supplied to the table via the onRowsRequest prop, but is controlled by a parent component via rows, onRowsChange, totalRows & onTotalRowsChange props.

Required props:

Example:

export const AsyncControlledTable = () => {
    
    const columns = getColumns();
    let [rows, setRows] = useState();
    let [totalRows, setTotalRows] = useState();

    const onRowsRequest = async (requestData, tableManager) => {
        const response = await fetch(`app/api/rows`, {
            method: 'post',
            body: {
                from: requestData.from,
                to: requestData.to,
                searchText: requestData.searchText,
                sort: requestData.sort,
            },
        }).then(response => response.json()).catch(console.warn);

        if(!response?.items) return;
        
        return {
            rows: response.items,
            totalRows: response.totalItems
        };
    }

    return (
        <GridTable
            columns={columns}
            onRowsRequest={onRowsRequest}
            rows={rows}
            onRowsChange={setRows}
            totalRows={totalRows}
            onTotalRowsChange={setTotalRows}
        />
    )
}

Async (Managed):

Use it if you need to fetch your data asynchrony, and manage it yourself (Useful when there are other places that should be able to fetch the same data).
All the data is supplied to the table via the rows prop, which should be updated using the onRowsRequest prop.
Note: react-grid-table will not necessarily ask for concurrent data, which means that "holes" in the data are possible. These "holes" needs to be filled with null/undefined items in order to ensure proper functionally.

To achieve this, you can use:

let mergedRows = tableManager.asyncApi.mergeRowsAt(rows, fetchedRows, at)

Required props:

Example:

const controller = new AbortController();

export const AsyncManagedTable = () => {
    
    const columns = getColumns();
    let rowsRef = useRef([]);
    let [totalRows, setTotalRows] = useState();

    const onRowsRequest = async (requestData, tableManager) => {
        const response = await fetch(`app/api/rows`, {
            method: 'post',
            body: {
                from: requestData.from,
                to: requestData.to,
                searchText: requestData.searchText,
                sort: requestData.sort,
            },
            signal: controller.signal,
        }).then(response => response.json()).catch(console.warn);

        if(!response?.items) return;

        rowsRef.current = tableManager.asyncApi.mergeRowsAt(rowsRef.current, response.items, requestData.from);

        setTotalRows(response.totalItems);
    }

    const onRowsReset = () => {
        rowsRef.current = [];
        setTotalRows();
        controller.abort();
    }

    return (
        <GridTable
            columns={columns}
            rows={rowsRef.current}
            onRowsRequest={onRowsRequest}
            onRowsReset={onRowsReset}
            totalRows={totalRows}
            requestDebounceTimeout={500}
        />
    )
}

Row-Editing

Row editing can be done by rendering the edit button using the cellRenderer property in the column configuration, then when clicked, it will control the editRowId prop, then the table will render the editing components for columns that are defined as editable (true by default), and as was defined in the editorCellRenderer which by default will render a text input.

Example:

// state
const [rowsData, setRows] = useState(MOCK_DATA);

// 'editRowId' can also be controlled.
// if using controlled state, you can call your 'setEditRowId' instead of 'tableManager.rowEditApi.setEditRowId' to set it directly on your state.
// the table will typicaly call 'onEditRowIdChange' to reset it if 'searchText', 'sort' or 'page' has changed.
// const [editRowId, setEditRowId] = useState(null)

// columns
let columns = [
    ...,
    {
        id: 'my-buttons-column',
        width: 'max-content',
        pinned: true,
        sortable: false,
        resizable: false,
        cellRenderer: ({ tableManager, value, data, column, colIndex, rowIndex }) => (
            <button 
                style={{marginLeft: 20}} 
                onClick={e => tableManager.rowEditApi.setEditRowId(data.id)}
            >&#x270E;</button>
        ),
        editorCellRenderer: ({ tableManager, value, data, column, colIndex, rowIndex, onChange }) => (
            <div style={{display: 'inline-flex'}}>
                <button 
                    style={{marginLeft: 20}} 
                    onClick={e => tableManager.rowEditApi.setEditRowId(null)}
                >&#x2716;</button>
                <button 
                    style={{marginLeft: 10, marginRight: 20}} 
                    onClick={e => {
                        let rowsClone = [...rowsData];
                        let updatedRowIndex = rowsClone.findIndex(r => r.id === data.id);
                        rowsClone[updatedRowIndex] = data;

                        setRowsData(rowsClone);
                        tableManager.rowEditApi.setEditRowId(null);
                    }
                }>&#x2714;</button>
            </div>
        )
    }
];

// render
<GridTable 
    columns={columns}
    rows={rowsData} 
    //editRowId={editRowId}
    //onEditRowIdChange={setEditRowId}
    ...
/>

For columns that hold values other than string, you'll need to define the setValue function on the column so the updated value won't override the original value.

Example:

setValue: ({value, data, setRow, column}) => {
    // value: '35', 
    // data: { ..., columnField: { fieldToUpdate: '27' }} 
    let rowClone = { ...data };
    rowClone[column.field].fieldToUpdate = value;
    setRow(rowClone);
}

Styling

Styling is done by CSS classes that you can easily override. the table's components are mapped with pre-defined classes that should cover any situation, and you can add your own custom class per column in the columns configuration using the className property.

License

© MIT