@nokacreative/generic-react-table v1.3.3

A generic table written in React and Typescript with many features.

View the demo here. The demo's repository can also be found here.

Installation

npm i @nokacreative/generic-react-table

or

yarn add @nokacreative/generic-react-table

Features

• Column sorting, resizing, reordering, and pinning
• Sorting
• Paging
• Searching
• Filtering
• Row selection (single and multiple)
• Integration with a server side
• Automatic handling (rendering, sort calculations, filter generation, etc.) of data types such as plain and rich text, numbers, dates, money, colours

Usage

Overview

1. Define your columns
2. Plug them and your data into <Table>

import { Table, TableColumn, DataType } from '@nokacreative/generic-react-table'
import { data } from './database'

const columns: TableColumn<UserModel>[] = [
  {
    headerText: 'Column 1',
    propertyPath: 'column1',
    type: DataType.PLAIN_TEXT,
  }
]

const App = () => (
  <Table columns={columns} data={data} />
)

Code Samples

Gives an overview of the code used in the demo. For the full code, see its repository.

All custom types that will be shown in these examples are described in-depth at the bottom of this document, in the "Comprehensive API reference" section.

Basic table

Below are the definitions used for this particular sample. The CUSTOM and RELATION data types give you a render() function for you to decide how you want to render the cell, while all other data types automatically render their contents based on the given propertyPath.

import { Table, TableColumn, DataType } from '@noka/generic-react-table'
import { database } from './database'

interface UserModel {
  id: string
  userName: string
  displayName: string
  dateJoined: number
  groupId: string
}

const columns = (groups: GroupModel[]): TableColumn<UserModel>[] => [
  {
    headerText: 'User Name',
    type: DataType.CUSTOM,
    render: (user: UserModel) => (
      <Link to={ROUTES.userDetails(user.id)}>{user.userName}</Link>
    ),
  },
  {
    propertyPath: 'displayName',
    headerText: 'Display Name',
    type: DataType.PLAIN_TEXT,
  },
  {
    propertyPath: 'groupId',
    headerText: 'Group',
    type: DataType.RELATION,
    relatedDataList: groups,
    render: (relatedGroup: GroupModel) => (
      <Link to={ROUTES.groupDetails(relatedGroup.id)}>{relatedGroup.name}</Link>
    ),
  },
  {
    propertyPath: 'dateJoined',
    headerText: 'Date Joined',
    type: DataType.DATE,
    showTime: true,
    defaultWidth: 'max-content',
  },
]

const App = () => (
  <Table columns={columns(database.groups)} data={database.users} />
)

Column sorting and resizing

const columns: TableColumn<GroupModel>[] = [
  {
    headerText: 'Name',
    type: DataType.CUSTOM,
    render: (group: GroupModel) => (
      <Link to={ROUTES.groupDetails(group.id)}>{group.name}</Link>
    ),
    isSortable: true,
    sortAccessor: (group: GroupModel) => group.name,
    defaultSortDirection: SortDirection.ASCENDING,
    isResizable: true,
    defaultWidth: '200px',
  },
  {
    propertyPath: 'description',
    headerText: 'Rich Description',
    type: DataType.RICH_TEXT,
    isResizable: true,
  },
  {
    propertyPath: 'numUsers',
    headerText: '# Users',
    type: DataType.NUMBER,
    isSortable: true,
    defaultWidth: '0.5fr',
  },
]

const App = () => (
  <Table columns={columns(database.groups)} data={database.users} />
)

Pinned columns and column reordering

Pinning columns allow them to stay in place, even if everything else needs to scroll. There is no new code in the column definitions for this example--all you need are two properties in the Table component:

<Table
  columns={columns}
  data={database.tags}
  numPinnedColumns={1} <--
  canReorderColumns    <--
/>

Minimum Number of Rows and Paging

Setting a minimum number of rows allows the table to stay a consistent length through different pages of possibly different data lengths. Ex. if min num rows are set to 5 when there are only 3 results:

<Table
  columns={columns}
  data={database.products}
  minNumRows={5}
  usePaging
  defaultPageSize={5}
  pageSizeOptions={[1, 2, 5, 10]}
  showResultCount
/>

Row selection

Single select and multiple-select are both supported.

function onSingleSelection(user: UserModel) {
  alert(`You have selected the user with ID ${user.id}, name ${user.userName}`)
}

function onMultipleSelections(_: UserModel, allSelections: UserModel[]) {
  setButtonDisabled(allSelections.length === 0)
}

<Table
  columns={columns(groups)}
  data={users}
  onRowSelected={onSingleSelection}
/>

<Table
  columns={columns(groups)}
  data={users}
  onRowSelected={onMultipleSelections}
  keepSelections
/>

Row Reordering

Row orders are persisted through paging, sorting, and filtering.

A move indicator is automatically added to each cell in the first column. A callback function can optionally be passed in for when a row is reordered.

function onRowReordred(row: ProductModel, fromIndex: number, toIndex: number) {
  ...
}

<Table
  columns={columns}
  data={products}
  useRowReordering
  onRowReordered={onRowReordred}
/>

Server-side Paging and Sorting

The necessary properties are useServerSidePaging and onPage(), and useServerSideSorting and onSort(). totalNumPages and totalNumResults must also be passed in when using server-side paging.

// Container
import { SortingRule } from '@noka/generic-react-table'

function doFetch() {
  fakeClient.fetchProducts(currParams.current).then((response: ServerResponse) => {
    setData(response.products) // <-- This data is passed into the view, which updates the table
    setTotalNumPages(response.totalNumPages)
    setTotalNumResults(response.totalNumResults)
    setLoading(false)
  })
}

function onSort(currentSortingRules: SortingRule<ProductModel>[]) {
  setLoading(true)
  currParams.current.sortingRules = currentSortingRules
  doFetch()
}

function onPage(pageIndex: number, pageSize: number) {
  setLoading(true)
  currParams.current.pageIndex = pageIndex
  currParams.current.pageSize = pageSize
  doFetch()
}

// View
<Table
  columns={columns}
  data={props.data}
  minNumRows={5}
  showResultCount

  // Paging
  usePaging
  useServerSidePaging
  onPage={props.onPage}
  totalNumPages={props.totalNumPages}
  totalNumResults={props.totalNumResults}
  // Optional
  defaultPageSize={DEFAULT_PAGE_SIZE}
  pageSizeOptions={[2, 3, 5]}

  // Sorting
  useServerSideSorting
  onSort={props.onSort}
  // Optional
  canSortMultipleColumns

  isLoading={props.isLoading}
/>

Search and filter

<Table
  columns={columns}
  data={database.people}
  isSearchable
  isFilterable
  tableName="People"
  showResultCount
/>

// Example columns
{
  propertyPath: 'age',
  headerText: 'Age',
  type: DataType.NUMBER,
  filterType: FilterType.EXACT_MATCH,
}

{
  propertyPath: 'dateOfBirth',
  headerText: 'Date of Birth',
  type: DataType.DATE,
  filterType: FilterType.RANGED,
}

Server-side search and filter

Works the same way as server-side paging and sorting; with the properties useServerSideSearching and onSearch(), and useServerSideFiltering and onFilter().

<Table
  columns={columns}
  data={props.data}

  // Search
  isSearchable
  useServerSideSearching
  onSearch={props.onSearch}

  // Filter
  isFilterable
  useServerSideFiltering
  onFilter={props.onFilter}

  // Necessary for either
  totalNumResults={props.totalNumResults}

  isLoading={props.isLoading}
  showResultCount
  tableName="People from Server"
/>

Style overriding

All colours are defined as CSS variables and scoped under the noka-table-colors class. By simply overriding that class's variables, the table's colours can be customized to your liking; refer to the last section of the API reference to see all availble variables.

Variables can be overriden via directly setting them in the aforementioned class, which will change all tables globally:

.noka-table-colors {
  --headerCellBg: #e2e2e2;
  --headerCellText: #181818;
  --active: #00cae4;
}

Or by adding an ID (or extra className) to the table, and scoping the colours there:

<Table id="my-table" {...} />

#my-table {
  --cellBg: #181818;
  --alternateCellBg: black;
}

A full list of the available variables, their default values, and their descriptions can be found in the "Style overriding - CSS colour variables" section under the API reference.

Text overriding

(Pardon the Google Translate)

All messages and formatters (eg. date and money) can be overriden.

import { MessageOverrides, FormatterOverrides } from '@nokacreative/generic-react-table'

const messageOverrides: MessageOverrides = {
  noData: (pluralEntityName?: string) => `il n'y a pas de ${pluralEntityName}`,
  noFilterResults: "Il n'y a aucun résultat pour les filtres donnés!",
  noSearchResults: "Il n'y a aucun résultat pour le terme de recherche donné!",
  filters: {
    moneySymbol: '€',
    togglerButtonTooltip: 'Filtre',
    clearButtonTooltip: 'Effacer tous les filtres',
    placeholders: {
      genericFilter: 'Filtre',
      exactMatch: 'exactement',
      partialMatch: 'contient',
      (etc.)
    },
    datePicker: {
      dateFormat: 'dd MMMM yyyy',
      locale: 'fr',
    },
  }
}

const formatterOverrides: FormatterOverrides = {
  date: (timeValue: number) =>
    new Date(timeValue).toLocaleDateString('fr-FR', {
      year: 'numeric',
      month: 'long',
      day: 'numeric',
    }),
  money: (value: number) => `€${value}`,
}

<Table
  {...}
  messageOverrides={messageOverrides}
  formatterOverrides={formatterOverrides}
/>

To see the full list of overridable properties, see the "Text Overrides" section under the API reference.

react-datepicker is used for the Datepicker. Thus, other than setting the locale in the overrides as written above, changing its locale contains a bit more steps; refer to the Localization section of the linked package to see how it's done.

Rich-Text Configurations

Rich text columns sanitize using a specific whitelist of formatting tags + <br> and <p> by default. You can override this behaviour in a variety of ways, such as disallowing line-breaks, setting your own sanitization options, or transforming specific tags into others. Below are some sample column definitions (with all non-relevant properties stripped out):

{
  headerText: 'No Line-breaks',
  disallowLineBreaks: true,
},
{
  headerText: 'Custom (only <b> allowed)',
  sanitizationOptions: {
    allowedTags: ['b'],
  },
},
{
  headerText: 'Custom (spans with class attribute allowed)',
  sanitizationOptions: {
    allowedTags: ['span'],
    allowedAttributes: {
      span: ['class'],
    },
  },
},
{
  headerText: 'Custom (transform <b> into <i>)',
  sanitizationOptions: {
    transformTags: { b: 'i' },
  },
}

To see the full list of options and their descriptions, refer to the "Rich Text Columns" sections in the API reference below.

Comprehensive API reference

Common enums

Data (Column) Types

There's also a self-explanatory SortDirection enum that is referenced below, with values of ASCENDING and DESCENDING.

Filter Types

Table component properties

Base

The function signature of headerCellTemplate is as such:

(
  headerText: string,
  columnDefinition: TableColumn<T>,
  sortIndicator: JSX.Element | undefined,
  onSort: (() => void) | undefined,
  filter: JSX.Element | undefined
) => JSX.Element

All properties below are technically optional, but required if you want the specific functionality defined by each header.

Paging

Row selection

Row reordering

Searching

Filtering

Server-only common properties

Column property break down

Common properties

Plain text columns

Rich text columns

Sanitization Options

The function signature for transformTags is as follows:

(
  tagName: string,
  attribs: { [attr: string]: string }
) => {
  tagName: string;
  attribs: { [attr: string]: string }
}

// Ex.
{
  transformTags: {
    ol: (tagName: string, attribs: { [attr: string]: string }) => {
      // do stuff
      return {
        tagName: 'ul',
        attribs: {
          class: 'foo'
        }
      }
    }
  }
}

You can also refer to the sanitize-html-react documentation to see usage samples.

Number and Money columns

Date columns

Colour columns

Relation columns

Custom columns

Custom Filters

Used for custom and relation columns.

Text

Number

Dropdown

Style overriding - CSS colour variables

Common

Table

Text overrides

Everything is optional.

General Messages

Filter Messages/Text (General)

Filter Placeholders

All of these are strings.

Datepicker

Formatters