react-select-table

A combination of item management (addition, deletion, sorting, etc.) using redux,
and a table component to display them.

Demo

Demo source code

Version 5.3.5

- Fixed 'this is undefined' error when calling a hook reference
- Fixed auto scrolling to the active row, when in an unloaded chunk, and the table width has changed since the chunk was last unloaded
- Added Alt+Click shortcut to select text instead of starting drag selection

Older changes

Features

* Item filtering
* Item searching (by just starting to type the first letters of the item)
* Multi-column sorting
* Pagination
* Resizable columns (widths can be saved and restored)
* Percentage based column sizing (can be used in resizable containers)
* Responsive column visibility
* Sticky header
* Performance optimized drag selection with automatic scrolling (even with uneven in height rows)
* Familiar shortcuts and selection behavior emulating native windows ListView
* Fully usable with only the keyboard
* Single and multi-row selection
* ListBox mode (explained below)
* Touch support (chromium based browsers only)
* Events (Selection changed, Columns resized, Items opened, Context menu)
* Modular state saving and restoring (ex. the items can be saved but not the sort order)
* Does not need margin for columns to be resized beyond the visible bounds
* Does not need margin for drag selecting beyond the visible bounds
* Easily customizable appearance using css variables (sass not required)

Keyboard and mouse shortcuts

$3

* Up / Down to select the previous/next item relative to the active item
* Home / End to select the first/last item
* Ctrl + Any of the above to set as active instead of select
* Click to select the item below the cursor
* Left / Right to set the row with the same index on the previous/next page active
* Shift + Any of the above to select all items in between
* Shift + Click below rows to select all items to the end of the page
* Ctrl + Shift + Any of the above to add to the previous selection instead of replacing it
* Double click to raise an items open event for the selected rows
* Click below rows to clear the selection
* Enter to select the active row if it's not selected, or to raise an items open event if it is selected
* Ctrl + Enter to toggle selection of the active row
* Ctrl + Click to toggle selection of the row below the cursor
* Ctrl + A to select all items
* Right click to raise a context menu event for the selected rows (also changes the selection in the same way a left click does, except if the row under the cursor is already selected)
* Alt + Right click to raise a context menu event for an empty selection, but without changing the selection
* Alt + Ctrl + Right click to raise a context menu event for the selected rows, without changing the selection
* Ctrl + Right click below rows to raise a context menu event for the selected rows, without clearing the selection
* Shift + Right click to bring up the browser's context menu
* Click + Drag to start drag selecting (you can also scroll while drag selecting)
* Ctrl + Click + Drag to add the drag selected rows to the previous selection instead of replacing it
* Alt + Click + Drag to select text instead of starting drag selection

$3

* Click below rows does not clear the selection
* Right click to raise a context menu event for the active row (does not change the selection, but sets the row below the cursor active)
* Right click below rows to raise a context menu event for an undefined active row, but without clearing the active row
* Alt + Right click to raise a context menu event for an undefined active row, but without changing the active row
* Alt + Ctrl + Right click to raise a context menu event for the active row, without changing the active row
* Ctrl + Right click to raise a context menu event for the selected rows, without changing the selection

$3

* Click on the green column separator + Drag to start resizing the column
* Move the cursor outside the table while dragging to start automatically scrolling
* If the table is overflowing horizontally (aka the scrollbar is visible), scroll with the wheel while dragging to expand or shrink the column
* Ctrl + Any of the above to keep the total width of the table constant

$3

* Click on a header title to toggle the sorting order for the column between ascending and descending
* Shift + Click on a header title to sort the items using this column after first sorting them with the previously selected columns (multiple column sorting)

$3

* Type any character while the table is focused to bring up the search dialog
* Up/Down to go to the previous/next match
* Press escape to close the search dialog

Touch gestures

$3

* Tap to select the row below the finger
* Tap below the rows to clear the selection
* Double tap to raise an items open event for the row below the finger
* Two-finger tap with both fingers on the same row to raise a context menu event for the selected rows (also changes the selection in the same way a simple tap does, except if the row is already selected)
* Two-finger tap with both fingers below the rows to clear the selection and raise a context menu event for the empty selection
* Two-finger tap with both fingers on separate rows to raise an items open event for the selected rows, without changing the selection
* Long tap to toggle selection of the row below the finger
* Long tap + Drag with a second finger to start drag selecting (you can also scroll with the second finger while drag selecting)

$3

* Tap below the rows does not clear the selection
* Two-finger tap with both fingers on the same row to raise a context menu event for the active row (does not change the selection, but sets the row active)
* Two-finger tap with both fingers below the rows to raise a context menu event for an undefined active row, but without clearing the active row

$3

* Tap on the green column separator + Drag to start resizing the column
* Move the finger outside the table while dragging to start automatically scrolling
* If the table is overflowing horizontally (aka the scrollbar is visible), scroll horizontally with a second finger anywhere on the table to expand or shrink the column

$3

* Tap on a header title to toggle the sorting order for the column between ascending and descending
* Long tap on a header title to sort the items using this column after first sorting them with the previously selected columns (multiple column sorting)

Migrating from version 4

This version is a complete rewrite, treat it as a completely different library

Quick start guide

Installation

``shell


Npm

npm install react-select-table

Yarn

yarn add react-select-table
`

$3

On every section there is example code given, if you want to follow along building the example
from an empty create-react-app, you'll also need these libraries:

`shell


Npm

npm install @reduxjs/toolkit react-redux @fortawesome/fontawesome-svg-core @fortawesome/react-fontawesome @fortawesome/free-solid-svg-icons sass axios

Yarn

yarn add @reduxjs/toolkit react-redux @fortawesome/fontawesome-svg-core @fortawesome/react-fontawesome @fortawesome/free-solid-svg-icons sass axios
`

Importing the stylesheet

$3

In your index.js, at the top:
`javascript
import 'react-select-table/dist/index.css';
`

$3

For the example code, we'll be using sass

In your App.js, at the top:
`javascript
import './App.scss';
`

In App.scss:
`scss
@use '~react-select-table/src/scss/style' as rst;
`

Setting up the store

Each table reducer is identified by a unique string, which is called the namespace of the reducer.
You will need it to dispatch actions for the reducer, to get state properties, and to pass it to the table component,
so it's a good idea to define it once, and export it to avoid typos.

To create a table reducer use the createTable function. It takes a namespace as the first argument,
and an object containing options as the second. You can see the default options as well as a description
of each option in optionsUtils.js, but we'll go through the most important ones here.

Each row to be added to the table must be an object (you can't add plain strings),
and as is the case for the reducer, it must also be identified by a unique string or number,
which is called the key of the row. The key can be the id of the item in the database,
or an auto-incrementing number or uuid if no database is involved. In any case, the key of the row should be
able to be derived from the row object, and that is the job of the keyBy option.
If the key of a row is just a property inside the object, you can simply set the keyBy option to
a string being the path to that property. In more complex cases you can set it to a function that takes
a row object as an argument and returns the key of the row.
Note that the key of the row is used internally as an object key,
meaning that the item key 1 is considered equal to '1', and that whenever you receive keys from the library
(ex. the selected keys on the onSelectionChange event handler), they are in string form regardless of the original type.

If a reducer isn't the root reducer, you must set the statePath option to a string being the path to the reducer.

$3

Say we're making a todo list, and our objects are of this format:
`typescript
interface Todo {
userId: number;
id: number;
title: string;
completed: boolean;
}
`
We'll set keyBy='id', and searchProperty='title' to enable searching by title.
We must also pick a namespace for the reducer, let's say todos. Our completed store.js code is:

`javascript
import { configureStore } from '@reduxjs/toolkit'
import { createTable } from 'react-select-table'

export const tableNamespace = 'todos'

export default configureStore({
reducer: createTable(tableNamespace, {
keyBy: 'id',
searchProperty: 'title'
})
})
`

In a typical app, where there other reducers as well, the code will look more like this:

`javascript
import { configureStore } from '@reduxjs/toolkit'
import { createTable } from 'react-select-table'

export const tableNamespace = 'todos'

export default configureStore({
reducer: {
todoTable: createTable(tableNamespace, {
keyBy: 'id',
searchProperty: 'title',
statePath: 'todoTable'
}),
...otherReducers
}
})
`

To complete the store setup, we need to add a store provider.

index.js
`jsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';

import { Provider } from 'react-redux'
import store from './store'

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(





);

// If you want to start measuring performance in your app, pass a function
// to log results (for example: reportWebVitals(console.log))
// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
reportWebVitals();
`

Adding the component

The component is exported as Table, and you can see the available props in TableProps.js.

The first required prop is namespace, which should be the same one that you gave to the reducer.

The second required prop is columns, which should be an array of column objects.
You can see the properties of a column object also in TableProps.js.
To set the title of the column, use the title property.
To specify how the content of the column is derived from a row object, you have three options:
1. If the content is derived from a single row property,
you can set the path of the column to a string being the path to that property.
If you stop here, the value of the row property will be displayed directly, but if you need more customization you
can set the render of the column to a function that takes the value of the row property as an argument
and returns the content to be displayed. Note that setting the path of the column, makes the column sortable.
2. If you don't set the path, the number of the row will be displayed in that column,
or passed to the render function if provided.
3. If the content is derived from multiple row properties, you can leave the path unset,
and use the second argument of the render function which is the entire row object,
to derive and return the content.

There is also a third argument passed to render, which is an object with a className property which you can set
to give a custom class to the cell.

Columns are also identified by a unique string, called the key of the column.
By default, if path is set it is used as the key, but if it's not, or there are multiple columns with the same path,
you must set the key property of the column to a unique string.

You can set the isHeader property of the column to true, to use th elements instead of td.

Finally, you can optionally set the defaultWidth of the column to a number,
which is the percentage of the table width that should be taken up by the column on the initial render.

$3

Continuing with the todo list example, we'll import the namespace from the store setup file.

We will then add our four columns:
1. The number of the row, with a title of 'A/I' (Auto increment)
2. The id of the item, with a title of 'Id', using th elements
3. The title of the item, with a title of 'Title'
4. The completion status of the item, with a title of 'Completed',
rendered as a checkmark or an x icon, which is colored using a css class. We'll use fontawesome for the icons.

Our code thus far is:

App.js
`jsx
import './App.scss'

import React from 'react'
import { Table } from 'react-select-table'
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
import { faCheck, faXmark } from '@fortawesome/free-solid-svg-icons'

import { tableNamespace } from './store'

const columns = [
{
title: "A/I",
defaultWidth: 10
},
{
title: "Id",
path: "id",
isHeader: true,
defaultWidth: 10
},
{
title: "Title",
path: "title",
defaultWidth: 50
},
{
title: "Completed",
path: "completed",
defaultWidth: 20,
render: (completed, todo, options) => {
options.className = completed ? "text-green" : "text-red"
return
}
}
];

export default function App() {
return