tty-table: Terminal and Browser Table Formatter

5.0.0 · active · verified Sun Apr 19

tty-table is a versatile JavaScript library designed to render tabular data in various environments, including Node.js command-line interfaces, web browsers, and browser developer consoles. Currently at stable version 5.0.0, the library sees moderate release activity, with recent updates focusing on bug fixes and dependency management. Its key differentiators include extensive configuration options for headers, columns, and data rows, supporting custom formatters for cell values, and the ability to handle both static datasets and streaming data in terminal applications. Unlike some CLI table libraries, tty-table provides a unified API for both terminal and browser rendering, offering flexibility for developers building multi-platform tools or debugging in the browser console.

Common errors

```
TypeError: Table is not a constructor
```
cause Attempting to import `Table` using a CommonJS `require` statement in a way that expects a default export, or trying to destructure a CommonJS `require` call incorrectly.

fix Use `const Table = require('tty-table');` for CommonJS environments or `import { Table } from 'tty-table';` for ES Modules.
```
Cannot read properties of undefined (reading 'configure') inside formatter
```
cause This typically occurs when a `formatter` function is defined as an arrow function, which lexically binds `this`, preventing access to the `tty-table` specific `this` context (e.g., `this.configure`, `this.resetStyle`).

fix Rewrite the `formatter` function using a traditional `function` keyword to ensure `this` context is correctly bound by `tty-table`: ```javascript { value: "Column", formatter: function(cellValue, columnIndex, rowIndex, rowData, inputData) { this.configure({ truncate: false }); // 'this' will now work return cellValue; } } ```

Warnings

breaking Since v5.0.0, column widths are strictly coerced to integers. If you were previously relying on non-integer widths or specific float-to-int conversion behavior, your table layout might change.
Fix: Ensure all `width` properties in your header configuration are explicitly defined as integers. Review layouts that might have implicitly relied on floating-point width calculations.
gotcha When using `formatter` functions for column-specific cell value transformations, fat arrow functions (`() => {}`) do not support scope overrides. This means features like `this.configure()` or `this.resetStyle()` within a formatter will not work correctly when defined as an arrow function.
Fix: Use a traditional `function` declaration (`function(cellValue, ...){...}`) for `formatter` callbacks if you need to access `this` context for methods like `this.configure()` or `this.resetStyle()`.

Install

npm install tty-table npm
yarn add tty-table yarn
pnpm add tty-table pnpm

Imports

Table
wrong:
```
const Table = require('tty-table');
```
correct:
```
import { Table } from 'tty-table';
```
While CommonJS `require` still works, ESM `import` is the recommended modern approach, especially when using TypeScript as the package ships with types.
TableOptions
```
import { Table, TableOptions, HeaderItem } from 'tty-table';
```
Type imports for configuration objects like TableOptions and HeaderItem enhance type safety and IDE autocompletion when defining table structures. Refer to the package's type definitions for a complete list of available types.

Quickstart

Demonstrates creating a basic table with custom headers, data (both array of arrays and array of objects), and rendering it to the console with styling and a custom formatter.

import { Table } from 'tty-table';

const header = [
  { value: "Name", align: "left", color: "green" },
  { value: "Age", align: "center", width: 5 },
  {
    value: "Occupation",
    formatter: (value: string) => value.toUpperCase(),
    color: "cyan",
    align: "right",
    width: 20
  }
];

const rows = [
  ["Alice", 30, "Software Engineer"],
  ["Bob", 24, "Data Scientist"],
  ["Charlie", 45, "Project Manager"],
  ["Diana", 28, "UX Designer"]
];

const options = {
  borderStyle: "solid",
  borderColor: "blue",
  headerAlign: "center",
  align: "left",
  width: "auto"
};

const t1 = new Table(header, rows, options);
console.log(t1.render());

// Example with a different data structure
const header2 = [
  { value: "Product", align: "left" },
  { value: "Price (USD)", align: "right",
    formatter: (price: number) => `$${price.toFixed(2)}`
  },
  { value: "In Stock", align: "center" }
];

const rows2 = [
  { product: "Laptop", price: 1200.50, inStock: true },
  { product: "Mouse", price: 25.99, inStock: false },
  { product: "Keyboard", price: 75.00, inStock: true }
];

const t2 = new Table(header2, rows2);
console.log(t2.render());

view raw JSON →