Package Exports

@visulima/tabular
@visulima/tabular/package.json
@visulima/tabular/style

Readme

@visulima/tabular

visulima tabular

A powerful and flexible CLI table and grid generator for Node.js, written in TypeScript. Create beautiful ASCII tables or grids with customizable borders, padding, and alignment. Supports Unicode, colors, and ANSI escape codes.

^{Daniel Bannert's open source work is supported by the community on GitHub Sponsors}

Features

Type-safe: Full TypeScript support
Unicode Support: Handles CJK characters and emojis correctly
ANSI Colors: Works with ANSI escape codes and colors
Flexible Styling: Customizable borders, padding, and alignment
Column Configuration: Individual column width and alignment settings
Header Support: Optional headers with custom styling
Border Styles: Multiple pre-defined border styles and custom border options
Cell Spanning: Support for rowSpan and colSpan
Word Wrapping: Automatic or configurable word wrapping
Truncation: Smart content truncation with customizable options

Installation

npm install @visulima/tabular

yarn add @visulima/tabular

pnpm add @visulima/tabular

Usage

The package provides two main classes for creating tables:

Table: High-level API for creating tables with headers and rows
Grid: Low-level API for more complex layouts and custom grid structures

Table Usage

The Table class provides a simple API for creating tables with headers and rows:

import { createTable } from "@visulima/tabular";

// Create a basic table
const table = createTable({
    style: {
        paddingLeft: 1,
        paddingRight: 1,
    },
    showHeader: true, // Show headers (default: true)
    wordWrap: true, // Enable word wrapping
    maxWidth: 100, // Maximum table width
});

// Add headers
table.setHeaders(["Name", { content: "Age", hAlign: "center" }, { content: "City", hAlign: "right" }]);

// Add rows
table.addRow(["John Doe", "30", "New York"]);
table.addRow([
    { content: "Jane Smith", colSpan: 2 }, // Span two columns
    "Los Angeles",
]);

// Add multiple rows at once
table.addRows(
    ["Bob", "25", "Chicago"],
    ["Alice", "28", "Boston"],
);

console.log(table.toString());

Output:

┌──────────┬─────┬─────────────┐
│ Name     │ Age │        City │
├──────────┼─────┼─────────────┤
│ John Doe │ 30  │ New York    │
├──────────┴─────┼─────────────┤
│ Jane Smith     │ Los Angeles │
├──────────┬─────┼─────────────┤
│ Bob      │ 25  │ Chicago     │
├──────────┼─────┼─────────────┤
│ Alice    │ 28  │ Boston      │
└──────────┴─────┴─────────────┘

Grid Usage

The Grid class provides more control over layout and styling:

import { createGrid } from "@visulima/tabular";

// Create a grid with 3 columns
const grid = createGrid({
    columns: 3,
    paddingLeft: 1,
    paddingRight: 1,
    gap: 1, // Gap between cells
});

// Add items with complex layouts
grid.addItems([
    { content: "Header", colSpan: 3, hAlign: "center" },
    { content: "Left", vAlign: "top" },
    { content: "Center\nMultiline", vAlign: "middle", rowSpan: 2 },
    { content: "Right", vAlign: "bottom" },
    { content: "Bottom Left" },
    { content: "Bottom Right" },
]);

console.log(grid.toString());

Output:

┌────────────────────────────┐
│           Header           │
├─────────┬─────────┬────────┤
│ Left    │ Center  │ Right  │
│         │Multiline│        │
├─────────┤         ├────────┤
│ Bottom  │         │ Bottom │
│ Left    │         │ Right  │
└─────────┴─────────┴────────┘

Advanced Features

Cell Styling

Both Table and Grid support rich cell styling:

import { createTable } from "@visulima/tabular";
import { red, green, blue, bgYellow, bgBlue, bold, yellow, white } from "@visulima/colorize";

const table = createTable();

// Example 1: Using function-based background color
table.addRow([
    {
        content: "Warning",
        backgroundColor: bgYellow, // Function that applies background color
        hAlign: "center",
        vAlign: "middle",
    },
    {
        content: "Error",
        backgroundColor: (text) => bgBlue(red(text)), // Custom color function
        colSpan: 2,
    },
]);

// Example 2: Using ANSI escape sequences directly
table.addRow([
    {
        content: "Custom",
        backgroundColor: {
            open: "\u001B[44m", // Blue background
            close: "\u001B[49m", // Reset background
        },
    },
    {
        content: "Status",
        backgroundColor: {
            open: "\u001B[42m", // Green background
            close: "\u001B[49m", // Reset background
        },
    },
]);

// Example 3: Combining with other styling options
table.addRow([
    {
        content: "Important Notice",
        backgroundColor: bgYellow,
        colSpan: 2,
        maxWidth: 20, // Maximum cell width
        truncate: true, // Enable truncation
        wordWrap: true, // Enable word wrapping
        style: {
            border: ["bold"],
            paddingLeft: 2,
        },
    },
]);

// Example 4: Demonstrating borderColor and foregroundColor
const tableWithBorderColors = createTable({
    style: {
        // Apply a global border color (e.g., blue)
        borderColor: blue,
    },
});

tableWithBorderColors.setHeaders(["Type", "Description"]);

tableWithBorderColors.addRow([
    // Cell with default border color, custom foreground
    { content: red("Error Text") },
    "This text uses the default blue border.",
]);

tableWithBorderColors.addRow([
    // Cell with custom border color (overrides global)
    {
        content: "Important",
        style: {
            borderColor: green, // Green border for this cell only
        },
    },
    "This cell has a green border.",
]);

tableWithBorderColors.addRow([
    // Cell with custom foreground and border color
    {
        content: bold(yellow("Warning")),
        style: {
            borderColor: yellow, // Yellow border for this cell
        },
    },
    "Bold yellow text with a yellow border.",
]);

tableWithBorderColors.addRow([
    // Cell with background and custom border color
    {
        content: "Info",
        backgroundColor: bgBlue, // Blue background
        style: {
            borderColor: white, // White border for this cell
        },
    },
    "White text on blue background with a white border.",
]);

console.log(tableWithBorderColors.toString());

The backgroundColor property can be specified in two ways:

As a function that takes the cell content as a string and returns the styled string
As an object with open and close properties containing ANSI escape sequences

You can combine background colors with:

Text colors and styles
Cell spanning (colSpan/rowSpan)
Alignment (hAlign/vAlign)
Content formatting (truncate/wordWrap)
Custom border styles
Custom padding

Dynamic Sizing

Control column and row sizes:

import { createGrid } from "@visulima/tabular";

const grid = createGrid({
    columns: 3,
    // Fixed column widths
    fixedColumnWidths: [10, 20, 15],
    // Fixed row heights
    fixedRowHeights: [1, 2, 1],
    // Maximum width (will scale down if needed)
    maxWidth: 100,
    // Auto-flow direction
    autoFlow: "row", // or "column"
});

API Reference

index

Classes

Grid

Defined in: grid.ts:40

A class that represents a grid layout with support for cell spanning, alignment, and borders

Constructors

new Grid()

new Grid(options): Grid

Defined in: grid.ts:53

Creates a new Grid instance

Parameters

options

GridOptions

Configuration options for the grid

Returns

Grid

Methods

addItem()

addItem(cell): this

Defined in: grid.ts:100

Adds a single item to the grid

Parameters

cell

GridCell

The cell to add

Returns

this

The grid instance for method chaining

addItems()

addItems(items): this

Defined in: grid.ts:110

Adds multiple items to the grid

Parameters

items

GridCell[]

Array of items to add

Returns

this

The grid instance for method chaining

setBorder()

setBorder(border): this

Defined in: grid.ts:140

Sets the border style for the grid

Parameters

border

BorderStyle

Border style configuration

Returns

this

The grid instance for method chaining

setColumns()

setColumns(columns): this

Defined in: grid.ts:120

Sets the number of columns in the grid

Parameters

columns

number

Number of columns

Returns

this

The grid instance for method chaining

setMaxWidth()

setMaxWidth(width): this

Defined in: grid.ts:161

Sets the maximum width for the grid

Parameters

width

number

Maximum width

Returns

this

The grid instance for method chaining

setRows()

setRows(rows): this

Defined in: grid.ts:130

Sets the number of rows in the grid

Parameters

rows

number

Number of rows

Returns

this

The grid instance for method chaining

setShowBorders()

setShowBorders(show): this

Defined in: grid.ts:151

Sets whether borders should be shown

Parameters

show

boolean

Whether to show borders

Returns

this

The grid instance for method chaining

toString()

toString(): string

Defined in: grid.ts:170

Converts the grid to a string representation

Returns

string

A string containing the rendered grid

Table

Defined in: table.ts:9

A versatile table generator for CLI applications.

Constructors

new Table()

new Table(options): Table

Defined in: table.ts:20

Initializes a new Table instance.

Parameters

options

TableOptions = {}

Configuration options for the table.

Returns

Table

Methods

addRow()

addRow(row): this

Defined in: table.ts:59

Adds a single row to the table body.

Parameters

row

TableCell[]

Array of cells representing the row.

Returns

this

The Table instance for chaining.

addRows()

addRows(...rows): this

Defined in: table.ts:72

Adds multiple rows to the table body.

Parameters

rows

...TableCell[][]

Array of rows to add.

Returns

this

The Table instance for chaining.

setHeaders()

setHeaders(headers): this

Defined in: table.ts:39

Sets the header rows for the table. Replaces any existing headers.

Parameters

headers

Array of header rows OR a single header row.

TableCell[] | TableCell[][]

Returns

this

The Table instance for chaining.

toString()

toString(): string

Defined in: table.ts:88

Renders the table to a string.

Returns

string

The string representation of the table.

Functions

createGrid()

function createGrid(options): Grid;

Defined in: grid.ts:1313

Creates a new grid instance with the specified options

Parameters

options

GridOptions

Configuration options for the grid

Returns

Grid

A new Grid instance

createTable()

function createTable(options?): Table;

Defined in: table.ts:239

Creates a new Table instance.

Parameters

options?

TableOptions

Configuration options for the table.

Returns

Table

A new Table instance.

Interfaces

BorderComponent

Defined in: types.ts:74

Properties

char

char: string;

Defined in: types.ts:75

width

width: number;

Defined in: types.ts:76

BorderStyle

Defined in: types.ts:82

Represents the style of the border for a table or grid.

Properties

bodyJoin

bodyJoin: BorderComponent;

Defined in: types.ts:84

Box vertical character.

bodyLeft

bodyLeft: BorderComponent;

Defined in: types.ts:86

Box vertical character.

bodyRight

bodyRight: BorderComponent;

Defined in: types.ts:88

Box vertical character.

bottomBody

bottomBody: BorderComponent;

Defined in: types.ts:90

Box horizontal character.

bottomJoin

bottomJoin: BorderComponent;

Defined in: types.ts:92

Box bottom join character.

bottomLeft

bottomLeft: BorderComponent;

Defined in: types.ts:94

Box bottom left character.

bottomRight

bottomRight: BorderComponent;

Defined in: types.ts:96

Box bottom right character.

joinBody

joinBody: BorderComponent;

Defined in: types.ts:98

Box horizontal character.

joinJoin

joinJoin: BorderComponent;

Defined in: types.ts:100

Box horizontal join character.

joinLeft

joinLeft: BorderComponent;

Defined in: types.ts:102

Box left join character.

joinRight

joinRight: BorderComponent;

Defined in: types.ts:104

Box right join character.

topBody

topBody: BorderComponent;

Defined in: types.ts:106

Box horizontal character.

topJoin

topJoin: BorderComponent;

Defined in: types.ts:108

Box top join character.

topLeft

topLeft: BorderComponent;

Defined in: types.ts:110

Box top left character.

topRight

topRight: BorderComponent;

Defined in: types.ts:112

Box top right character.

GridItem

Defined in: types.ts:30

Extended by

TableItem

Properties

backgroundColor?

optional backgroundColor:
  | {
  close: string;
  open: string;
 }
  | (text) => string;

Defined in: types.ts:32

Background color for the entire cell (including padding)

colSpan?

optional colSpan: number;

Defined in: types.ts:34

Number of columns this cell spans

content

content: Content;

Defined in: types.ts:36

Content to display in the cell

hAlign?

optional hAlign: HorizontalAlignment;

Defined in: types.ts:38

Horizontal alignment of the content

maxWidth?

optional maxWidth: number;

Defined in: types.ts:40

Maximum width of the cell content before truncation

rowSpan?

optional rowSpan: number;

Defined in: types.ts:42

Number of rows this cell spans

truncate?

optional truncate: boolean | TruncateOptions;

Defined in: types.ts:44

Options for controlling how text is truncated when it exceeds maxWidth

vAlign?

optional vAlign: VerticalAlignment;

Defined in: types.ts:46

Vertical alignment of the content

wordWrap?

optional wordWrap: boolean | Omit<WordWrapOptions, "width">;

Defined in: types.ts:48

Options for controlling word wrapping (takes precedence over truncate)

GridOptions

Defined in: types.ts:210

Defines the style options.

Extends

Style

Properties

autoColumns?

optional autoColumns: number;

Defined in: types.ts:212

Default number of columns for auto-generated cells

autoFlow?

optional autoFlow: AutoFlowDirection;

Defined in: types.ts:214

Direction of auto-flow when adding items

autoRows?

optional autoRows: number;

Defined in: types.ts:216

Default number of rows for auto-generated cells

border?

optional border: BorderStyle;

Defined in: types.ts:122

Border style configuration.

Inherited from

Style.border

columns

columns: number;

Defined in: types.ts:218

Number of columns in the grid

defaultTerminalWidth?

optional defaultTerminalWidth: number;

Defined in: types.ts:220

Default terminal width to use for calculations (defaults to 80)

fixedColumnWidths?

optional fixedColumnWidths: number[];

Defined in: types.ts:222

Fixed column widths

fixedRowHeights?

optional fixedRowHeights: number[];

Defined in: types.ts:224

Fixed row heights

gap?

optional gap: number;

Defined in: types.ts:226

Gap between cells

maxWidth?

optional maxWidth: number;

Defined in: types.ts:228

Maximum width for the entire grid

paddingLeft?

optional paddingLeft: number;

Defined in: types.ts:127

Left padding for all cells.

Inherited from

Style.paddingLeft

paddingRight?

optional paddingRight: number;

Defined in: types.ts:132

Right padding for all cells.

Inherited from

Style.paddingRight

rows?

optional rows: number;

Defined in: types.ts:230

Number of rows in the grid (0 for auto)

showBorders?

optional showBorders: boolean;

Defined in: types.ts:232

Whether to show borders (only relevant if border is defined)

terminalWidth?

optional terminalWidth: number;

Defined in: types.ts:234

Terminal width to use for calculations (defaults to actual terminal width)

truncate?

optional truncate: boolean | TruncateOptions;

Defined in: types.ts:236

Whether to truncate content

wordWrap?

optional wordWrap: boolean | WordWrapOptions;

Defined in: types.ts:238

Whether to wrap content in cells (takes precedence over truncate)

Style

Defined in: types.ts:118

Defines the style options.

Extended by

GridOptions

Properties

border?

optional border: BorderStyle;

Defined in: types.ts:122

Border style configuration.

paddingLeft?

optional paddingLeft: number;

Defined in: types.ts:127

Left padding for all cells.

paddingRight?

optional paddingRight: number;

Defined in: types.ts:132

Right padding for all cells.

TableItem

Defined in: types.ts:59

Extends

GridItem

Properties

backgroundColor?

optional backgroundColor:
  | {
  close: string;
  open: string;
 }
  | (text) => string;

Defined in: types.ts:32

Background color for the entire cell (including padding)

Inherited from

GridItem.backgroundColor

colSpan?

optional colSpan: number;

Defined in: types.ts:34

Number of columns this cell spans

Inherited from

GridItem.colSpan

content

content: Content;

Defined in: types.ts:36

Content to display in the cell

Inherited from

GridItem.content

hAlign?

optional hAlign: HorizontalAlignment;

Defined in: types.ts:38

Horizontal alignment of the content

Inherited from

GridItem.hAlign

href?

optional href: string;

Defined in: types.ts:63

Optional URL for making the cell content a hyperlink.

maxWidth?

optional maxWidth: number;

Defined in: types.ts:40

Maximum width of the cell content before truncation

Inherited from

GridItem.maxWidth

rowSpan?

optional rowSpan: number;

Defined in: types.ts:42

Number of rows this cell spans

Inherited from

GridItem.rowSpan

style?

optional style: CellStyle;

Defined in: types.ts:69

TODO: Check if this is needed Style options for the cell.

truncate?

optional truncate: boolean | TruncateOptions;

Defined in: types.ts:44

Options for controlling how text is truncated when it exceeds maxWidth

Inherited from

GridItem.truncate

vAlign?

optional vAlign: VerticalAlignment;

Defined in: types.ts:46

Vertical alignment of the content

Inherited from

GridItem.vAlign

wordWrap?

optional wordWrap: boolean | Omit<WordWrapOptions, "width">;

Defined in: types.ts:48

Options for controlling word wrapping (takes precedence over truncate)

Inherited from

GridItem.wordWrap

TableOptions

Defined in: types.ts:138

Defines the options for table construction.

Properties

columnWidths?

optional columnWidths: number | number[];

Defined in: types.ts:144

Fixed column widths for specific columns. Content exceeding the width will be truncated based on the truncate options. Can specify width for all columns with a single number or for specific columns with an array.

defaultTerminalWidth?

optional defaultTerminalWidth: number;

Defined in: types.ts:147

Default terminal width to use for calculations (defaults to 80)

gap?

optional gap: number;

Defined in: types.ts:152

Gap between cells (overrides style.gap)

maxWidth?

optional maxWidth: number;

Defined in: types.ts:157

Maximum width for the entire table.

rowHeights?

optional rowHeights: number | number[];

Defined in: types.ts:164

Fixed row heights for specific rows. Content exceeding the height will be truncated with an ellipsis symbol on the last line. Can specify height for all rows with a single number or for specific rows with an array.

showHeader?

optional showHeader: boolean;

Defined in: types.ts:169

Whether to show the header of the table

style?

optional style: Partial<Style & object>;

Defined in: types.ts:174

The style options for the table

terminalWidth?

optional terminalWidth: number;

Defined in: types.ts:186

Terminal width to use for calculations (defaults to actual terminal width)

transformTabToSpace?

optional transformTabToSpace: number;

Defined in: types.ts:191

The number of spaces to use for tab characters.

truncate?

optional truncate: TruncateOptions;

Defined in: types.ts:196

Options for controlling how text is truncated when it exceeds maxWidth

wordWrap?

optional wordWrap: boolean | Omit<WordWrapOptions, "width">;

Defined in: types.ts:201

Whether to enable word wrapping.

Type Aliases

AutoFlowDirection

type AutoFlowDirection = "column" | "row";

Defined in: types.ts:206

BorderType

type BorderType = "bottom" | "middle" | "top";

Defined in: types.ts:207

CellStyle

type CellStyle = object;

Defined in: types.ts:8

Style options for a cell.

Type declaration

border?

optional border: string[];

Array of style names for the cell's border.

head?

optional head: string[];

Array of style names for the cell's head.

paddingLeft?

optional paddingLeft: number;

Left padding of the cell content.

paddingRight?

optional paddingRight: number;

Right padding of the cell content.

Content

type Content = bigint | boolean | number | string | null | undefined;

Defined in: types.ts:3

GridCell

type GridCell = Content | GridItem;

Defined in: types.ts:52

Input type for a cell, can be primitive or an options object

HorizontalAlignment

type HorizontalAlignment = "center" | "left" | "right";

Defined in: types.ts:205

TableCell

type TableCell = Content | TableItem;

Defined in: types.ts:72

VerticalAlignment

type VerticalAlignment = "bottom" | "middle" | "top";

Defined in: types.ts:204

style

Variables

ASCII_BORDER

const ASCII_BORDER: BorderStyle;

Defined in: style.ts:132

ASCII border style using only ASCII characters.

DEFAULT_BORDER

const DEFAULT_BORDER: BorderStyle;

Defined in: style.ts:6

Default border style using standard box-drawing characters.

DOTS_BORDER

const DOTS_BORDER: BorderStyle;

Defined in: style.ts:90

Border style using dots for the border.

DOUBLE_BORDER

const DOUBLE_BORDER: BorderStyle;

Defined in: style.ts:48

Double-line border style using Unicode box-drawing characters.

MARKDOWN_BORDER

const MARKDOWN_BORDER: BorderStyle;

Defined in: style.ts:111

Border style using Markdown syntax.

MINIMAL_BORDER

const MINIMAL_BORDER: BorderStyle;

Defined in: style.ts:27

Minimal border style using only horizontal lines.

NO_BORDER

const NO_BORDER: BorderStyle;

Defined in: style.ts:153

No border style.

ROUNDED_BORDER

const ROUNDED_BORDER: BorderStyle;

Defined in: style.ts:69

Border style with rounded corners using Unicode box-drawing characters.

cli-table3 - Pretty unicode tables for the command line
table - Formats data into a string table.

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js' release schedule. Here's a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guidelines.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

License

The visulima tabular is open-sourced software licensed under the MIT