# frame-one-table

> A react table with maximum flexibility.

Latest version **0.3.17** (published 2023-10-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install frame-one-table
pnpm add frame-one-table
yarn add frame-one-table
bun add frame-one-table
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.17 |
| Published | 2023-10-29 |
| First published | 2021-05-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^18.16.0 |
| Dependencies | 0 |
| Unpacked size | 95.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | frame_one_software |
| Maintainers | christopher_powroznik |

## Links

- npm: https://www.npmjs.com/package/frame-one-table
- Repository: https://github.com/Frame-One-Software/frame-one-table
- Homepage: https://github.com/Frame-One-Software/frame-one-table#readme
- Issues: https://github.com/Frame-One-Software/frame-one-table/issues
- npm.io page: https://npm.io/package/frame-one-table

## Recent versions

- 0.3.17 (latest) — 2023-10-29
- 0.3.15 — 2023-06-24
- 0.3.13 — 2023-06-23
- 0.3.12 — 2022-10-26
- 0.3.11 — 2022-07-08
- 0.3.10 — 2022-07-05
- 0.3.9 — 2022-07-01
- 0.3.8 — 2022-07-01
- 0.3.7 — 2022-07-01
- 0.3.6 — 2022-07-01
- 0.3.4 — 2022-07-01
- 0.3.1 — 2022-07-01
- 0.2.10 — 2022-05-14
- 0.2.9 — 2022-05-02
- 0.2.7 — 2022-04-22
- … 15 more at https://npm.io/package/frame-one-table/versions

## README

[![Frame One Table Logo](./meta/banner1_white.png)](https://frame-one-software.github.io/frame-one-table/)
<br/>
[![NPM](https://img.shields.io/npm/v/frame-one-table.svg)](https://www.npmjs.com/package/frame-one-table)
[![NPM](https://img.shields.io/npm/dt/frame-one-table.svg)](https://www.npmjs.com/package/frame-one-table)
[![GITHUB](https://img.shields.io/github/issues/Frame-One-Software/frame-one-table.svg)](https://github.com/Frame-One-Software/frame-one-table/issues)

### [➡️ Try out the table in the Storybook! ⬅️](https://frame-one-software.github.io/frame-one-table/)

version 0.2.0 had some big changes to how data is passed around, will document eventually

## Installation

### npm
```bash
npm install frame-one-table
```

### yarn
```bash
yarn add frame-one-table
```

## Usage

Use Frame One Table's `TableGenerator` component like any React component; and pass it props to configure your table as desired.

```tsx
import * as React from 'react'
import {TableGenerator} from "frame-one-table";

class Example extends React.Component {
  render () {
    return (
      <TableGenerator
        columnOptions={[]}
        data={[]}
      />
    )
  }
}
```

## Props

### Table Generator `TableGeneratorProps`
| Prop | Type | Description |
| --- | :---: | --- |
| `data` | `TableData` | Pass in the data here to be rendered
| `columnOptions` | `ColumnOption[]` | Options to determine the rendering of each column
| `paginatorProps` | `IPaginatorProps[]` | Props for controlling the paginator
| `sortable` | `boolean` | Determine a default for each column as sortable. This can be overridden by the columnOptions
| `showSortIcons` | `boolean` | Toggle to hide or show the arrow icons in the header cells when a column is sortable. Defaults true
| `showHeader` | `boolean` | Hide or show the header row. Defaults true
| `showBody` | `boolean` | Hide or show the body part of the table. Not sure why you would want to hide it if you are using this library. Defaults true
| `headerClassName` | `string` | className applied to the header row
| `rowClassName` | `string` | className applied to each row in the body
| `headerCellClassName` | `string` | className applied to each cell in the header row
| `rowCellClassName` | `string` | className applied to each cell in the table body
| `headerStyle` | `CSSProperties` | style tag applied to the header row
| `rowStyle` | `CSSProperties` | style tag applied to each row in the body
| `headerCellStyle` | `CSSProperties` | style tag applied to each cell in the header row
| `rowCellStyle` | `CSSProperties` | style tag applied to each cell in the table body
| `rowFilter` | `ContextFunctionRow<boolean>` | filter out rows that are shown // TODO
| `paginationControlsRender` | `ContextFunctionPagination<ReactNode>` | create your own pagination controls // TODO
| `loading` | `boolean` | loading, its nice to use this instead of increment loading since we can just block a table // TODO
| `loadingOverlay` | `ContextFunctionData<ReactNode>` | loading, its nice to use this instead of increment loading since we can just block a table // TODO

### Column Options `ColumnOption`
| Prop | Type | Description |
| --- | :---: | --- |
| `key` | `string` `number` | key that is used to extract the correct value from the row's object (string) or array (number)
| `headerValue` | `any` | Label for the header cell (ie. First Name)
| `valueFormatter` | `ContextFunctionCell<any>` | Format function to run the values for the column's body cells through before displaying them (ie. (height) => height + "cm"). Does not modify the value used to compare for sorting the column
| `headerRender` | `ContextFunctionCell<ReactNode>` | Custom render function for the header cell
| `cellRender` | `ContextFunctionCell<ReactNode>` | Custom render function for the body cells of this column
| `headerCellClassName` | `string` | className applied to the header cell
| `rowCellClassName` | `string` | className applied to the body cells of this column
| `headerCellStyle` | `CSSProperties` | style tag applied to the header cell
| `rowCellStyle` | `CSSProperties` | style tag applied to the body cells of this column
| `sortable` | `boolean` | Toggle if this column can be sorted. Takes precedent over the "sortable" prop from TableGeneratorProps
| `showSortIcons` | `boolean` | Toggle to hide or show the arrow icons in the header cell if the column is sortable. Takes precedent of the "showSortIcons" props from TableGeneratorProps
| `sortFunction` | `(a: any, b: any, aRow: TableDataEntry, bRow: TableDataEntry, data: TableData, columns: ColumnOption[], sortConfiguration: ISortStyle) => number` | Custom sort function for the column where a & b are the values. If not custom sort is applied, the library will attempt to sort automatically based on the primitive data type
| `hidden` | `boolean` | Toggle for hiding a column... Perhaps if a column becomes hidden based on certain conditions on your end, change this to false instead of creating a whole new set of column options

### Paginator Props `IPaginatorProps`
| Prop | Type | Description |
| --- | :---: | --- |
| `show` | `boolean` | Show or hide the paginator. Defaults false
| `limitLabel` | `string` | String shown next to the drop-down for choosing the limit (ie. Showing X - Y of Z)
| `currentLimit` | `number` | Currently selected limit for the table
| `limitOptions` | `number[]` | Array of numbers representing options for what limits can be chosen via the drop-down
| `total` | `number` | Total number of results in the table or pool of data. Used to calculate the last index for the "go to last" button
| `onLimitChange` | `(newLimit: number) => void` | Handler for changing the limit per page via the drop-down
| `enableGoPrevious` | `boolean` | Toggle for if the "go to first" and "previous" buttons should be enabled
| `enableGoNext` | `boolean` | Toggle for if the "go to last" and "next" buttons should be enabled
| `showGoToFirstButton` | `boolean` | Hide or show the "go to first" button. Defaults true
| `showGoToLastButton` | `boolean` | Hide or show the "go to last" button. Defaults true
| `currentOffset` | `number` | Current offset of the pagination, indexed at 0
| `availableOffsets` | `number[]` | Array of numbers for which pages should be accessible via the paginator (indexed at 0 - ie. [0, 1, 2, 3, 4], will be displayed as [1, 2, 3, 4 ,5] by the library)
| `onOffsetChange` | `(newOffset: number) => void` | Handler for changing the selected offset page

### Table Data Types
| Name | Type | Notes |
| --- | :---: | --- |
| `TableDataEntryArray` | `any[]` | // TODO; currently not supported
| `TableDataEntryJSON` | `{[key: string]: any}` |
| `TableData` | `Array<TableDataEntryArray>` or `Array<TableDataEntryJSON>` | The data for the table
| `TableDataEntry` | `TableDataEntryArray` or `TableDataEntryJSON` | Represents a single row
| `TableDataEntry` | `TableDataEntryArray` or `TableDataEntryJSON` | Represents a single row

### Context Helpers
| Name | Type |
| --- | :---: |
| `ContextFunctionData<R>` | `(data: TableData) => R`
| `ContextFunctionCell<R>` | `(value: any, row: TableDataEntryArray or TableDataEntryJSON, key: string or number, data: TableData, index?: number) => R`
| `ContextFunctionRow<R>` | `(row: TableDataEntryArray or TableDataEntryJSON, key: string or number, data: TableData, index?: number) => R`
| `ContextFunctionPagination<R>` | `(pageSize: number, pageIndex: number, goToPage: (page: number) => void, data: TableData) => R`

---
_Source: https://npm.io/package/frame-one-table · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._