@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, iSimpleTableRow, iSimpleTableSort, SimpleTable } from '@asup/simple-table';

... inside REACT component

<SimpleTable
  id?: string;
  headerLabel?: string;
  fields: iSimpleTableField[];
  keyField: string;
  data: iSimpleTableRow[];
  selectable?: boolean;
  currentSelection?: Key[];
  setCurrentSelection?: (ret: Key[]) => void;
  showSearch?: boolean;
  showFilter?: boolean;
  showPager?: boolean;
  initialFilterSelected?: boolean;
  filterLabel?: string;
  searchLabel?: string;
  onWidthChange?: (ret: (string | undefined)[]) => void;
  onPagerChange?: (ret: {firstRow: number; pageRows: number}) => void
  tableClassName?: string;
  inputGroupClassName?: string;
  filterLabelClassName?: string;
  filterCheckClassName?: string;
  searchLabelClassName?: string;
  searchInputClassName?: string;
  headerBackgroundColor?: string;
/>

Properties

| Prop | Description | Default | | :----------------------- | :----------------------------------------------------------------------------------------------------- | :----------------------------: | | id | Unique row id | simple-table | | headerLabel | Title used in the at the top of the table | 'Simple table' | | fields | List of columns in the table | | | keyField | Field containing the unique key for each row | | | data | Data to display, must contain a unique key field | | | selectable | Indicates if rows can be selected, using a checkbox | false | | currentSelection | Currently selected row keys | | | setCurrentSelection | Function to update the selected row keys, must be used in conjunction with the selectable indicator | | | 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 | | | onPagerChange | Callback after changing pager | | tableClassName | Class names to apply to the table element. | '' | | ~~inputGroupClassName~~ | Not currently implemented | form-group | | ~~filterLabelClassName~~ | Not currently implemented | form-check-label | | filterCheckClassName | Class names to apply to the checkboxes in the table. The default works well with bootstrap 5.2 | form-check-input | | searchLabelClassName | Class names to apply to the search label. The default works well with bootstrap 5.2 | form-label | | searchInputClassName | Class names to apply to the search input. The default works well with bootstrap 5.2 | form-control form-control-sm | | mainBackgroundColor | Background colour applied | white | | headerBackgroundColor | Background colour applied to the header row, used when other rows scroll under it | white |

Input data

Input data should be an array of objects

interface iSimpleTableRow {
  [key: string]: unknown;
}

e.g.

{
  id: 2,
  first_name: 'Paul',
  last_name: 'Thomas',
  car_make: 'Ferrari',
  car_model: 'Penis extension',
},

however, there are no restrictions on data type for each element. Complex objects will require a render function to be supplied, and sort/search/filter functions if they are required.

Column definition

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

interface iSimpleTableField {
    name: string;
    label?: string;
    hidden?: boolean;
    width?: string;
    sortFn?: (a: iSimpleTableRow, b: iSimpleTableRow, sortBy: iSimpleTableSort) => number;
    searchFn?: (a: iSimpleTableRow, searchText: string) => boolean;
    filterOutFn?: (a: iSimpleTableRow) => boolean;
    headerRenderFn?: (a: iSimpleTableHeaderRenderProps) => JSX.Element
    renderFn?: (a: iSimpleTableCellRenderProps) => JSX.Element;
}

e.g.

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

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 = (a: iSimpleTableRow, b: iSimpleTableRow, sortBy: iSimpleTableSort) => {
  return (a[sortBy.name] as string).localeCompare(b[sortBy.name] as string);
};

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: iSimpleTableRow, searchText: string) => {
  return ((rowData.car_make as string | null) ?? '').toLowerCase().includes(searchText.toLowerCase().trim());
};

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: iSimpleTableRow) => { return (rowData.car_make as string | null) === null; };

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 {
  columnNumber: number;
  field: iSimpleTableField;
}

interface iSimpleTableCellRenderProps extends iSimpleTableHeaderRenderProps {
  cellField: string;
  rowData: iSimpleTableRow;
  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 the server

"configurations": [
  {
    "type": "chrome",
    "request": "attach",
    "port": 9222,
    "name": "Attach to Browser debug",
    "webRoot": "${workspaceFolder}",
    "sourceMapPathOverrides": {
      "/__parcel_source_root/*": "${webRoot}/*"
    }
  },
  {
    "name": "Launch NPM web server",
    "command": "npm start",
    "request": "launch",
    "type": "node-terminal",
    "cwd": "${workspaceRoot}",
    "env": {
      "PORT": "1234"
    },
    "serverReadyAction": {
      "pattern": "Server running at (http://localhost:[0-9]+)",
      "uriFormat": "%s",
      "action": "openExternally"
    }
  }
]