@datasketch/monkeytab — API Reference

The complete props reference for the <MonkeyTable> React component.

Install

npm install @datasketch/monkeytab

React 18 or 19 is required as a peer dependency.

Quick Start

import { MonkeyTable } from '@datasketch/monkeytab';

function App() {
  return (
    <MonkeyTable
      columns={[
        { id: 'Name' },
        { id: 'Age', type: 'Number' },
        { id: 'Active', type: 'Boolean' },
      ]}
      rows={[
        { Name: 'Alice', Age: 30, Active: true },
        { Name: 'Bob', Age: 25, Active: false },
      ]}
      onChange={(rows) => console.log('Updated:', rows)}
      height="auto"
    />
  );
}

<MonkeyTable> Props

Data

Sorting

Selection Actions

Grouping

Row Coloring

Pagination

Layout

Permissions

Toolbar

Locale & Formatting

Registry Extensions

See EXTENDING.md for usage details.

MonkeyTableColumn

interface MonkeyTableColumn {
  id: string;                              // column key (used in row data)
  label?: string;                          // display label — defaults to id
  type?: FieldType;                        // defaults to 'Text'
  options?: FieldOptions;                  // type-specific options
  description?: string;                    // header tooltip / caption text
  descriptionDisplay?: 'tooltip' | 'caption';  // how description renders (default: 'tooltip')
  icon?: ReactNode;                        // custom column header icon
  render?: CellRendererFn;                 // custom cell renderer for this column
  hidden?: boolean;                        // hide column but keep data accessible
  editable?: boolean;                      // per-column read-only override
  width?: number;                          // initial width in pixels (default: 180)
  minWidth?: number;                       // minimum width (default: 80)
  maxWidth?: number;                       // maximum width (default: 600)
  sortable?: boolean;                      // can this column be sorted (default: true)
  align?: 'left' | 'center' | 'right';     // cell text alignment
  color?: string | CellColorFn;            // column color — static string or per-cell fn
}

type CellColorFn = (
  row: Record<string, Value>,
  value: Value,
  fieldId: string,
) => string | undefined;

Column coloring (column.color)

Three shapes, from simplest to most flexible:

• Static (string) — any CSS color. Every cell in the column plus the header gets a soft tint of that color. Good for marking a non-editable column, flagging a column that needs attention, or grouping related columns visually.
• Rule array (ColorRule[]) — JSON-serializable conditional formatting. Each rule is { when: ColorCondition, color: string }. Rules evaluate top-down; first match wins. Header stays default in this mode. Works in the JSON config form.
• Function (CellColorFn) — (row, value, fieldId) => string | undefined. For anything the rule array can't express: palettes, numeric interpolation, cross-field math. Header stays default. Prop-API only (functions aren't JSON-serializable).

Tints always blend with color-mix(… 30%, white) so dark colors stay readable, and compose cleanly with the row-level colorBy tint and the in-search yellow highlight.

<MonkeyTable
  columns={[
    { id: 'Name' },
    // Static: the whole "CreatedAt" column + header reads as a read-only band.
    { id: 'CreatedAt', type: 'Date', editable: false, color: '#f1f5f9' },
    // Rule array: red < 50, green ≥ 90, else untouched. Also works in JSON config.
    {
      id: 'Score',
      type: 'Number',
      color: [
        { when: { op: 'lt', value: 50 }, color: '#fee2e2' },
        { when: { op: 'gte', value: 90 }, color: '#dcfce7' },
      ],
    },
    // Function: same effect but with a mid-range yellow band, and arbitrary logic.
    {
      id: 'Priority',
      color: (_row, value) => {
        if (value === 'P0') return '#fecaca';
        if (value === 'P1') return '#fed7aa';
        return undefined;
      },
    },
  ]}
  rows={rows}
/>

Rule operators. ColorCondition is a tagged union keyed by op:

Every operator accepts an optional field: string to compare against a different column's value instead of the cell's own — useful for "tint the Status cell when Owner is empty":

color: [
  { when: { op: 'empty', field: 'Owner' }, color: '#fef3c7' },
]

For callers who want to reuse the same evaluator outside the grid (e.g., in a summary widget), evaluateColorRules(rules, row, value) is exported too:

import { evaluateColorRules } from '@datasketch/monkeytab';
const tint = evaluateColorRules(col.color as ColorRule[], row, row.Score);

In the JSON config form (<MonkeyTableFromConfig>), string and ColorRule[] are both accepted. The function form stays prop-API-only.

Field Types

Config-driven API

If you'd rather describe a whole table as one JSON blob — for example to store a user's table layout, serve a table from a REST endpoint, or have an LLM emit it from a sample of rows — use <MonkeyTableFromConfig>.

import { MonkeyTableFromConfig, type MonkeyTableConfig } from '@datasketch/monkeytab';

const config: MonkeyTableConfig = {
  columns: [
    { id: 'Name' },
    { id: 'Age', type: 'Number', options: { format: 'decimal' } },
    { id: 'Signup', type: 'Date', options: { dateFormat: 'iso' } },
    { id: 'Status', type: 'SingleSelect', options: {
      options: [
        { value: 'active', label: 'Active', color: '#22c55e' },
        { value: 'paused', label: 'Paused', color: '#f59e0b' },
      ],
    } },
    { id: 'Website', type: 'URL' },
  ],
  rows: [
    { Name: 'Alice', Age: 30, Signup: '2024-01-05', Status: 'active',  Website: 'https://example.com' },
    { Name: 'Bob',   Age: 25, Signup: '2024-02-10', Status: 'paused',  Website: 'https://example.org' },
  ],
  settings: {
    editable: true,
    height: 'auto',
    pageSize: 25,
    locale: 'en-US',
  },
};

<MonkeyTableFromConfig config={config} onChange={setRows} />

Shape

interface MonkeyTableConfig {
  schemaVersion?: number;              // reserved for future migrators
  columns: MonkeyTableConfigColumn[];  // same as MonkeyTableColumn, minus render/icon
                                        //   and with color narrowed to string
  rows: Array<Record<string, Value>>;
  settings?: MonkeyTableConfigSettings;
}

settings is a flat bucket that mirrors the scalar/enum props documented above — editable, height, pageSize, locale, groupBy, sortBy, dateDisplayFormat, etc. Anything not serializable (React handlers, custom renderers/editors, render/icon on a column, functions/constraints, presence, conditional-coloring functions) stays as ordinary component props on <MonkeyTableFromConfig>. Static column.color (CSS string) is allowed in the config; the function form is prop-API-only.

resolveConfig

If you'd rather keep using <MonkeyTable> directly, import resolveConfig to turn a config into the flat prop object it consumes:

import { MonkeyTable, resolveConfig } from '@datasketch/monkeytab';

const props = resolveConfig(config);
<MonkeyTable {...props} onChange={setRows} />

The two forms are interchangeable — <MonkeyTableFromConfig> is a thin forwardRef wrapper that does exactly this internally.

Keyboard Shortcuts

Header Interactions

Examples

Editable table with change tracking

<MonkeyTable
  columns={[
    { id: 'Task' },
    { id: 'Priority', type: 'SingleSelect', options: {
      options: [
        { value: 'high', label: 'High', color: '#fee2e2' },
        { value: 'medium', label: 'Medium', color: '#fef9c3' },
        { value: 'low', label: 'Low', color: '#dcfce7' },
      ]
    }},
    { id: 'Done', type: 'Boolean' },
  ]}
  rows={[
    { Task: 'Write docs', Priority: 'high', Done: false },
    { Task: 'Fix bug #42', Priority: 'medium', Done: true },
  ]}
  onChange={(rows) => console.log(rows)}
  height={300}
  showRowNumbers
/>

Read-only table with compact mode

<MonkeyTable
  columns={[
    { id: 'Metric' },
    { id: 'Q1', type: 'Number', options: { precision: 0, thousandsSeparator: true } },
    { id: 'Q2', type: 'Number', options: { precision: 0, thousandsSeparator: true } },
  ]}
  rows={[
    { Metric: 'Revenue', Q1: 120000, Q2: 145000 },
    { Metric: 'Expenses', Q1: 98000, Q2: 102000 },
  ]}
  editable={false}
  compactMode
  height={200}
  rowHeight="short"
/>

Per-column options

<MonkeyTable
  columns={[
    { id: 'Id', type: 'Number', editable: false, width: 80, sortable: false, align: 'center' },
    { id: 'Name', type: 'Text', width: 250, minWidth: 150, maxWidth: 400 },
    { id: 'Price', type: 'Number', align: 'right', width: 120 },
    { id: 'Notes', type: 'Text' },
  ]}
  rows={rows}
  editable
/>

Server-side pagination and sorting

const [page, setPage] = useState(1);
const [sortField, setSortField] = useState<string | null>(null);
const [sortDir, setSortDir] = useState<'asc' | 'desc' | null>(null);
const { data, total, isLoading } = useFetchRows({ page, sortField, sortDir });

<MonkeyTable
  columns={columns}
  rows={data}
  totalRows={total}
  page={page}
  pageSize={100}
  onPageChange={setPage}
  paginationMode="simple"
  paginationLoading={isLoading}
  sortBy={sortField}
  sortDirection={sortDir}
  onSortChange={(field, dir) => {
    setSortField(field);
    setSortDir(dir);
    setPage(1);  // reset to first page on sort change
  }}
/>

Spanish locale with custom translations

<MonkeyTable
  columns={columns}
  rows={rows}
  locale="es-CO"
  language="es"
  dateDisplayFormat="locale"
  currencyCode="COP"
  translations={{ 'toolbar.addRow': 'Nueva fila' }}
  onChange={handleChange}
/>

Custom file upload

<MonkeyTable
  columns={[
    { id: 'Name' },
    { id: 'Photo', type: 'Image' },
    { id: 'Resume', type: 'Attachment' },
  ]}
  rows={rows}
  onUpload={async (file, fieldType) => {
    const form = new FormData();
    form.append('file', file);
    const res = await fetch('/api/upload', { method: 'POST', body: form });
    const { url } = await res.json();
    return url;
  }}
/>