use-table-tools

React Hooks for building kickass react table components

Introduction

use-table-tools is a React Hooks library for building kickass react table components.

It features:

• flexbox table with adjustable column configuration
• checkboxes with multi select
• client side sorting
• shifting columns into or off view
• number of visible columns per screen resolution

Quick Start

import { useTableTools } from 'use-table-tools';

function Table() {
  const { ...utils } = useTableTools({
    layout: [''],
    columns: [],
    totalItems: 0,
  });

  return <div>hello from table component</div>;
}

Usage

Inside your React project directory, run the following:

yarn add use-table-tools

or with npm

npm install use-table-tools

API

Parameters

• layout?: { [key: number]: string[] } | string[]: layout of the table. Can be a string of flex props per column ['0 0 25%', '1 1 35%', '0 0 20%', '0 0 20%'] or an object with flex props per breakpoint where the key is a breakpoint and the value is a flex props per column.

const layout = {
  280: ['0 0 100%'],
  348: ['0 0 50%', '0 0 50%'],
  768: ['0 0 35%', '1 1 35%', '0 0 30%'],
  1280: ['0 0 25%', '1 1 35%', '0 0 20%', '0 0 20%'],
};

• columns: ColumnProps[]: define a shape of your data by providing what items should exist on the table component. It will accept and array of objects with the label, fieldKey and locked properties. Where fieldKey is the key name on you data object, rest is props for the table tools
• totalItems: number: total items per page, required for the checkboxes to determin the state when all items selected
• clientSortBy?: SortProps: initial client sort for the table
• checkedItems?: string[]: initialize with already checked items

Return Values

• switchColumns: (from: string, to: string) => void: provide colums keys from sortKey to sortKey and they will get replaced
• switchCurrentLayout: (currentLayout: string[]) => void: will switch current layout to the given one and will update visible and offset columns. Also used to automatically adjust if layout has breakpoints defined.
• offsetColumns: (obj?: { includeVisible: boolean }) => ColumnProps[]: shows offset columns with the ability to include visible ones as well
• onSelection: (items: string[]) => void: should be applied to master checkbox input onClick action with visible item ids.
• deselectAll: () => void: clears the state of selected item ids
• selectAll: (checkedItems: string[]) => void: selects all items
• checkboxToggle: (evt: ChangeEvent<HTMLInputElement>) => void: toggles checkbox by id
• checkboxShiftToggle: (evt: ChangeEvent<HTMLInputElement>) => void: toggles checkbox by id and selects/deselects a range when shift key is on
• checkboxState: (id: string) => boolean: returns a boolean state for the checkbox by id
• clientSortMethod: (a: object, b: object) => number: method to be used in a sort function, like ramda sort
• changeSortDirection: (direction: SortProps['direction']) => void: change current sort direction by specifying next direction
• toggleSortDirection: () => void: toggle current sort field direction
• toggleSortByKey: (fieldKey: string) => void: toggle sort direction on a field key
• sortData: (sortProps: SortProps) => void: sorts data by provided sortField and direction props
• activeSort: (sortProps: SortProps) => boolean: checks the state of the current active sort by key and direction
• activeSortKey: (key: string) => boolean: checks the state of the current active sort by key
• getCheckboxProps: ({...}) => CheckboxProps: spread checkbox props on the checkbox input

Options

Global Configuration

React Context API

<TableTools>{(utils) => <div />}</TableTools>

const utils = useTableToolsContext();

Examples

In progress...

LICENSE

MIT