@asup/simple-table

@asup/simple-table

REACT table, because I wanted one that took an array of objects as an input. Sort, filter and search functions can be added. Includes column resize.

Installation

# with npm
npm install @asup/simple-table

Usage

import {
  ISimpleTableField,
  ISimpleTableSort,
  ISimpleTableSortFn,
  SimpleTable,
  simpleTableSortFn,
} from "@asup/simple-table";

... inside REACT component

interface SimpleTableProps<T extends object> extends React.ComponentPropsWithoutRef<"table"> {
  id: string;
  headerLabel?: string;
  fields: ISimpleTableField<T>[];
  keyField: keyof T;
  data: T[];
  selectable?: boolean;
  currentSelection?: Key[];
  setCurrentSelection?: (ret: Key[]) => void;
  showHeader?: boolean;
  showSearch?: boolean;
  showFilter?: boolean;
  showPager?: boolean;
  initialFilterSelected?: boolean;
  filterLabel?: string;
  searchLabel?: string;
  onWidthChange?: (ret: { name: keyof T; width: string }[]) => void;
  onPagerChange?: (ret: { firstRow: number; pageRows: number }) => void;

  tableClassName?: string;
  inputGroupClassName?: string;
  filterLabelClassName?: string;
  filterCheckClassName?: string;
  searchLabelClassName?: string;
  searchInputClassName?: string;

  mainBackgroundColor?: string;
  headerBackgroundColor?: string;
  selectedBackgroundColor?: string;
  selectInactiveColor?: string;
  selectActiveColor?: string;
}

Properties

Prop	Description	Default
id	Unique id applied to the table element	None
headerLabel	Title displayed at the top of the table when showHeader is true	None
fields	List of columns in the table	None
keyField	Field containing the unique key for each row	None
data	Data to display, must contain a unique key field	None
selectable	Indicates if rows can be selected, using a checkbox	false
currentSelection	Currently selected row keys	[]
setCurrentSelection	Function to update selected row keys (used with selectable)	None
showHeader	Indicates whether to show the header title area	true
showSearch	Indicates whether to show the search input. All fields with a defined search function will be searched	true
showFilter	Indicates whether to show the filter checkbox	false
showPager	Indicates whether to show the pager in the footer	true
initialFilterSelected	Indicates whether the filter checkbox is checked on the initial render	false
filterLabel	Label for the filter checkbox	Filter
searchLabel	Label for the search input	Search
onWidthChange	Callback after changing column widths by dragging	None
onPagerChange	Callback after changing pager values	None
tableClassName	Class names to apply to the table element	""
inputGroupClassName	Class names for the search/filter input group container	form-group
filterLabelClassName	Class names to apply to the filter label	form-check-label
filterCheckClassName	Class names to apply to filter checkboxes	form-check-input
searchLabelClassName	Class names to apply to the search label	form-label
searchInputClassName	Class names to apply to the search input	form-control form-control-sm
mainBackgroundColor	Background color applied to the table wrapper	white
headerBackgroundColor	Background color applied to the header row	white
selectedBackgroundColor	Background color applied to selected rows	rgba(0, 0, 0, 0.8)
selectInactiveColor	Color for unchecked selection controls	rgb(0, 0, 0, 0.2)
selectActiveColor	Color for checked selection controls	rgb(255, 153, 0)

Input data

Input data should be an array of objects

interface PersonRow {
  id: number;
  first_name: string;
  last_name: string;
  car_make: string | null;
}

e.g.

{
  id: 2,
  first_name: 'Paul',
  last_name: 'Thomas',
  car_make: 'Lotus',
},

Complex objects are supported. If you need custom formatting for sorting/filtering/rendering, provide the field callbacks.

You do not need to extend a base interface. Any object shape works.

Column definition

Specify the fields to use in the table in the following format

interface ISimpleTableField<T> {
  name: keyof T;
  label?: string;
  hidden?: boolean;
  width?: string;
  sortFn?: (a: T, b: T, sortBy: ISimpleTableSort<T>) => number;
  searchFn?: (a: T, searchText: string) => boolean;
  filterOutFn?: (a: T) => boolean;
  columnFilterValueFn?: (value: unknown) => string[];
  headerRenderFn?: (a: ISimpleTableHeaderRenderProps<T>) => JSX.Element;
  renderFn?: (a: ISimpleTableCellRenderProps<T>) => JSX.Element;
}

e.g.

interface PersonRow {
  id: number;
  first_name: string;
  car_make: string | null;
}

const fields: ISimpleTableField<PersonRow>[] = [
  { name: 'id', hidden: true },
  {
    name: 'first_name',
    label: 'First name',
    searchFn: (rowData, searchText) =>
      rowData.first_name.toLowerCase().includes(searchText.toLowerCase().trim()),
    sortFn: simpleTableSortFn,
  },
  ...,
  {
    name: 'car_make',
    label: 'Make',
    searchFn: (rowData, searchText) =>
      (rowData.car_make ?? '')
        .toLowerCase()
        .includes(searchText.toLowerCase().trim()),
    sortFn: simpleTableSortFn,
    renderFn: ({ rowData }) => {
      return rowData.car_make ? <div>{rowData.car_make}</div> : <div>No car</div>;
    },
    filterOutFn: (rowData) => rowData.car_make === null,
  },
  ...,
];

Column header search and filter

When generating options for column header filters, the table automatically handles arrays and objects by inspecting individual values. Array elements are each treated as a separate option; plain objects use their string representation.

Use columnFilterValueFn when you need custom conversion for sort/filter semantics. It should return one or more string values used by the table for column filtering and sort comparison text.

Use renderFn for display only. It should return a React element (JSX.Element) for the cell UI and should not be used to define filter/sort values.

Filter out function

Specify how an each row should be filtered when the filter box is checked, on a field by field basis. Should return a truthy or falsy value. NB A true value will remove the row.

const filterOutFn = (rowData: PersonRow) => rowData.car_make === null;

Search function

Specify how an each row should be compared against the text in the search box, on a field by field basis. Should return a truthy or falsy value.

const searchFn = (rowData: PersonRow, searchText: string) => {
  return (rowData.car_make ?? '').toLowerCase().includes(searchText.toLowerCase().trim());
};

Sort function

Specify a column sort function, where sortBy returns the name and sort direction returned.
NB do not use the sort direction in the sorting algorithm, this will be applied by the table, however it is available for reference.

const sortFn: ISimpleTableSortFn<PersonRow> = (a, b, sortBy) => {
  return String(a[sortBy.name]).localeCompare(String(b[sortBy.name]));
};

// Default sort helper can be used directly.
const fieldsWithDefaultSort: ISimpleTableField<PersonRow>[] = [
  { name: "first_name", label: "First name", sortFn: simpleTableSortFn },
  { name: "car_make", label: "Make", sortFn: simpleTableSortFn },
];

Header Cell and Body Cell rendering

If no custom render function for the field is specified for the cell or the header, then the field will be rendered as a string.

A custom render function can be supplied to alter this, which is supplied with the column number, field name and row data as an object. It must return a valid JSX element.

interface ISimpleTableHeaderRenderProps<T> {
  columnNumber: number;
  field: ISimpleTableField<T>;
}

interface ISimpleTableCellRenderProps<T> extends ISimpleTableHeaderRenderProps<T> {
  cellField: keyof T;
  rowData: T;
  rowNumber: number;
}

e.g.

const headerRenderFn({ columnNumber, field }) => (
  <>
    {columnNumber}:{' '}
    <span>
      {field.name}
    </span>
  </>
);

const renderFn = ({ columnNnumber, cellField, rowData }:ISimpleTableCellRenderProps):JSX.Element => {
  return rowData.car_make ? <div>{rowData.car_make as string}</div> : <div>No car</div>;
};

VS code launch settings

Use these configurations to attach to chrome, then launch Storybook

"configurations": [
  {
    "type": "chrome",
    "request": "attach",
    "port": 9222,
    "name": "Attach to Browser debug",
    "webRoot": "${workspaceFolder}",
    "sourceMapPathOverrides": {
      "/__parcel_source_root/*": "${webRoot}/*"
    }
  },
  {
    "name": "Launch Storybook",
    "command": "npm run storybook",
    "request": "launch",
    "type": "node-terminal",
    "cwd": "${workspaceRoot}",
    "serverReadyAction": {
      "pattern": "Local:\\s+(http://localhost:[0-9]+/?)+",
      "uriFormat": "%s",
      "action": "openExternally"
    }
  }
]