@element-public/react-table v1.0.0

Table

Description

The Table is an efficient way to display data in rows and columns.

See live demos on storybook

Storybook Table Demos

Install bundle from npm-e

npm i @element-public/react-components @element-public/themes

Optional: install the component individually

npm i @element-public/react-table @element-public/themes

Open ~/.npmrc in an editor and add the following line to enable the @element-public scope:

@element-public:registry=https://npm.platforms.engineering

Troubleshooting

See below if you have never installed a package from Bayer's npm-enterprise or run into the following error:

npm ERR! code E401
npm ERR! Unable to authenticate, your authentication token seems to be invalid.
npm ERR! To correct this please trying logging in again with:
npm ERR!     npm login

Setup an access token

See the devtools npm-e guide to learn how to create an access token if this is the first time you are using a npm-e package at Bayer or you do not have a line that starts with the following in your ~/.npmrc file:

//npm.platforms.engineering/:_authToken=

Table Modes

The table component can be used in 1 of 3 modes. Composed, generated, and virtualized.

Composed

Composed is the most basic way to use table and is manually built like a traditional table with sub-components including TableHeader, TableBody, TableRow, TableHeaderCell, and TableCell. This mode does not have features such as pagination or sorting - please see Generated below.

Generated

You can create a generated table by passing in your data and a columns schema. The columns and rows will be built for you. This allows for a number of additional features such as pagination, sorting, and more. See the column schema below.

For best performance for larger datasets use pagination or see virtualized below.

Virtualized

Virtualized is a variation of a generated table that can provide much better performance for very large datasets without the need for pagination. It uses and alternate technique that only renders content that is visible in the specified window.

Virtualized tables require a fixed height be set.

Column Schema (Generated/Virtualized)

We use and extend react-table v7 under the hood. See their Column Options for even more documentation.

Expandable Rows

There are 2 main types of expandable rows. The first is a set of rows that follow the same column layout and may contain one or more sub-rows. The second allows for any arbitrary content to be displayed below an expanded row.

Common expandable rows setup

1. Enable expandable rows by setting the Table prop expandable to true. Example <Table expandable />
2. Add a column to your column schema to implement the expansion buttons
   1. Use the column schema headerTemplate field to implement a Button or IconButton that includes {...row.getToggleAllRowsExpandedProps()}.
   2. Use the column schema displayTemplate field to implement a Button or IconButton that includes {...row.getToggleRowExpandedProps()}.

Example:

// Note: This controls/indicates all rows being expanded or collapsed.
const expanderHeaderTemplate = ({
    getToggleAllRowsExpandedProps,
    isAllRowsExpanded
}) => (
    <IconButton dense {...getToggleAllRowsExpandedProps?.()}>
        <Icon
            iconSize='small'
            icon={
                isAllRowsExpanded
                    ? 'keyboard_arrow_down'
                    : 'keyboard_arrow_right'
            }
        />
    </IconButton>
);

// Note: This controls each individual row expanding or being collapsed.
const expanderDisplayTemplate = (
    // Note: This method signature will likely be simplified in v6.
    value,
    original,
    id,
    editable,
    onCellUpdate,
    row
) => (
    <IconButton {...row.getToggleRowExpandedProps()} dense>
        <Icon
            iconSize='small'
            icon={`keyboard_arrow_${row.isExpanded ? 'down' : 'right'}`}
        />
    </IconButton>
);

const columns = [
    {
        id: 'expander',
        headerTemplate: expanderHeaderTemplate,
        displayTemplate: expanderDisplayTemplate
    },
    { header: 'Title', accessor: 'title' },
    { header: 'Cost', accessor: 'cost' },
    { header: 'Count', accessor: 'count' },
    { header: 'Progress', accessor: 'progress' }
];

Same schema expandable rows

After following the common steps above, add the subRows field (object array) to your data schema/shape to hold the expandable/collapsible row data. This should match the parent data schema/shape.

Example:

const data = [
    {
        title: 'device',
        cost: '$11',
        count: 2,
        progress: 52,
        subRows: [
            {
                title: 'transportation',
                cost: '$15',
                count: 0,
                progress: 98
            },
            {
                title: 'wind',
                cost: '$23',
                count: 79,
                progress: 45
            }
        ]
    }
    //... rest of data
];

Custom expandable rows

After following the common steps above you will need to pass an expandableRowTemplate to the Table. This is a function that will return jsx to render your expanded content.

const expandedRowTemplate = ({ row }) => (
    // return any content you want, here we will just output the row values
    <Padding tag='pre'>
        <code>{JSON.stringify({ values: row.values }, null, 2)}</code>
    </Padding>
);

// ...
<Table expandedRowTemplate={expandedRowTemplate} expandable data={data} columns={columns}>

Initially/Always Expanded

You can also have a Table start with all expanded rows already open using initiallyExpanded Table prop. If you don't need collapsible rows, then you can ignore the expander column setup above.

Custom properties

Most properties for a TableRow or TableCell can be customized using one of several methods.

rowProps & headerRowProps

Note: this section will refer to rowProps, but headerRowProps works identically however, it is specific to the header row and can only be passed to the Table component.

To send custom props to TableRow you can use the Table prop rowProps. This can be either a simple object or a function. Using a function gives you the added benefit of receiving rowData and rowIndex, allowing for additional logic.

// Object
<Table
rowProps={{
    className: 'custom-class__x',
    onClick: () => {console.log('You clicked a row.')}
}}
/>

// Function
<Table
rowProps={
    (rowData, rowIndex)=> {
        // example custom props here
        className= !rowData?.firstName ? 'data__missing-name' : '',
        onClick: () => {console.log(`You clicked row ${rowIndex}.`, rowData)}

    }
}
/>

These are just a few examples of custom props, but you can pass in almost any valid TableRow or HtmlElement prop.

Additionally, you can have even more control by adding a rowProps field on a per record basis. This may also be an object or function.

const data = useMemo(() => [
    {
        name: 'Sponge Bob',
        rowProps: { expandable: true }
    },
    {
        name: 'Optimus Prime',
        rowProps: (rowData, rowIndex) => {
            onMouseEnter: () => {
                doSomethingInteresting(rowData, rowIndex);
            };
            onMouseLeave: () => {
                doSomethingInteresting2(rowData, rowIndex);
            };
        }
    },
    { name: 'Pickle Rick' }
]);

return <Table data={data} />;

rowProps Conflicts

In the case of prop collisions between those defined at the Table level and those defined in a data item, the data item wins. Given the following example

const data =[{name: 'A', rowProps: {className:'class_a'}}];

return (<Table rowProps={{className:'class__b'}} data={data}>)

The rendered class for the row with name A will be class\_\_a.

cellProps & headerCellProps

Note: this section will refer to cellProps, but headerCellProps works identically, but is specific to the header cells.

To send custom props to TableCell you can use the Table prop cellProps. This can be either a simple object or a function. Using a function gives you the added benefit of receiving the cell object, allowing for additional logic.

// Object
<Table
cellProps={{
    className: 'custom-class__x',
    onClick: () => {console.log('You clicked a cell.')}
}}
/>

// Function
<Table
cellProps={
    (cell)=> {
        // example custom props here
        className= !cell?.column.header === 'firstName' ? 'data__first-name' : '',
        onClick: () => {console.log(`You clicked '${cell?.column.header}' cell with value '${cell?.value}'.`)}

    }
}
/>

These are just a few examples of custom props, but you can pass in almost any valid TableCell or HtmlElement prop.

Additionally, you can have even more control by adding a cellProps field to a column config object. This may also be an object or function.

const columns = [
    {
        header: 'Name',
        accessor: 'name',
        cellProps: { expandable: true }
    },
    {
        header: 'Age',
        accessor: 'age',
        cellProps: cell => {
            onMouseEnter: () => {
                doSomethingInteresting(cell);
            };
            onMouseLeave: () => {
                doSomethingInteresting2(cell);
            };
        }
    }
];

cellProps Conflicts

In the case of prop collisions between those defined at the Table level and those defined in a column, the column prop wins. Given the following example

const columns = [
    { header: 'Name', accessor: 'name', cellProps: { className: 'class_a' } }
];

return <Table cellProps={{ className: 'class__b' }} columns={columns} />;

The rendered class for the column Name will be class\_\_a.

Using References & Imperative Functions

Table supports the use of react references. You will receive an object with a reference to the table and the following imperative functions:

{
    clearSortBy, // a function to reset sorting
        resetResizing, // a function to reset resizing
        table; // the table reference
}

Example reference usage:

    const tableRef = useRef();
    const handleScroll = () => {
        tableRef.current.table.scrollIntoView();
    };

    return (
        <>
            <Table
                ref={tableRef}
                data={data}
                columns={columns}
            />
            <div style={{ marginTop: '600px' }}>
                <button type='button' onClick={handleScroll}>
                    Scroll Table Into View
                </button>
            </div>
        </>

Table Props

Table Render Props

Table Deprecated Render Props

Table Events

Table Breaking Changes

Table Body Props

Table Body Render Props

Table Cell Props

Table Cell Deprecated Props

Table Cell Render Props

Table Cell Breaking Changes

Table Footer Props

Table Footer Render Props

Table Header Props