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({
    maxWidth: 100, // Maximum table width
    showHeader: true, // Show headers (default: true)
    style: {
        paddingLeft: 1,
        paddingRight: 1,
    },
    wordWrap: true, // Enable word wrapping
});

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

// Add rows
table.addRow(["John Doe", "30", "New York"]);
table.addRow([
    { colSpan: 2, content: "Jane Smith" }, // 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,
    border: DEFAULT_BORDER,
});

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

console.log(grid.toString());

Output:

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

Advanced Features

Cell Styling

Both Table and Grid support rich cell styling:

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

const table = createTable();

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

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

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

// 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
    {
        backgroundColor: bgBlue, // Blue background
        content: "Info",
        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({
    // Auto-flow direction
    autoFlow: "row", // or "column"
    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,
});

API Reference

index

Classes

Grid

Defined in: grid.ts:65

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

Constructors

Constructor

new Grid(options): Grid;

Defined in: grid.ts:90

Creates a new Grid instance

Parameters

options

GridOptions

Configuration options for the grid

Returns

Grid

Methods

addItem()

addItem(cell): this;

Defined in: grid.ts:138

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:148

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:178

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:158

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:198

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:168

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:188

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:207

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

Constructor

new Table(options): Table;

Defined in: table.ts:24

Initializes a new Table instance.

Parameters

options

TableOptions = {}

Configuration options for the table.

Returns

Table

Methods

addRow()

addRow(row): this;

Defined in: table.ts:60

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:77

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:43

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:93

Renders the table to a string.

Returns

string

The string representation of the table.

Functions

createGrid()

function createGrid(options): Grid;

Defined in: grid.ts:1416

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:257

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:70

Properties

char

char: string;

Defined in: types.ts:71

width

width: number;

Defined in: types.ts:72

BorderStyle

Defined in: types.ts:78

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

Properties

bodyJoin

bodyJoin: BorderComponent;

Defined in: types.ts:80

Box vertical character.

bodyLeft

bodyLeft: BorderComponent;

Defined in: types.ts:82

Box vertical character.

bodyRight

bodyRight: BorderComponent;

Defined in: types.ts:84

Box vertical character.

bottomBody

bottomBody: BorderComponent;

Defined in: types.ts:86

Box horizontal character.

bottomJoin

bottomJoin: BorderComponent;

Defined in: types.ts:88

Box bottom join character.

bottomLeft

bottomLeft: BorderComponent;

Defined in: types.ts:90

Box bottom left character.

bottomRight

bottomRight: BorderComponent;

Defined in: types.ts:92

Box bottom right character.

joinBody

joinBody: BorderComponent;

Defined in: types.ts:94

Box horizontal character.

joinJoin

joinJoin: BorderComponent;

Defined in: types.ts:96

Box horizontal join character.

joinLeft

joinLeft: BorderComponent;

Defined in: types.ts:98

Box left join character.

joinRight

joinRight: BorderComponent;

Defined in: types.ts:100

Box right join character.

topBody

topBody: BorderComponent;

Defined in: types.ts:102

Box horizontal character.

topJoin

topJoin: BorderComponent;

Defined in: types.ts:104

Box top join character.

topLeft

topLeft: BorderComponent;

Defined in: types.ts:106

Box top left character.

topRight

topRight: BorderComponent;

Defined in: types.ts:108

Box top right character.

GridItem

Defined in: types.ts:29

Extended by

TableItem

Properties

backgroundColor?

optional backgroundColor: AnsiColorObject | AnsiColorFunction;

Defined in: types.ts:31

Background color for the entire cell (including padding)

colSpan?

optional colSpan: number;

Defined in: types.ts:33

Number of columns this cell spans

content

content: Content;

Defined in: types.ts:35

Content to display in the cell

foregroundColor?

optional foregroundColor: AnsiColorObject | AnsiColorFunction;

Defined in: types.ts:37

Foreground color for the entire cell (including padding)

hAlign?

optional hAlign: HorizontalAlignment;

Defined in: types.ts:39

Horizontal alignment of the content

maxWidth?

optional maxWidth: number;

Defined in: types.ts:41

Maximum width of the cell content before truncation

rowSpan?

optional rowSpan: number;

Defined in: types.ts:43

Number of rows this cell spans

truncate?

optional truncate: boolean | TruncateOptions;

Defined in: types.ts:46

Options for controlling how text is truncated when it exceeds maxWidth

vAlign?

optional vAlign: VerticalAlignment;

Defined in: types.ts:48

Vertical alignment of the content

wordWrap?

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

Defined in: types.ts:50

Options for controlling word wrapping (takes precedence over truncate)

GridOptions

Defined in: types.ts:157

Options specific to Grid construction.

Extends

BaseRenderingOptions.Style

Properties

autoColumns?

optional autoColumns: number;

Defined in: types.ts:159

Default number of columns for auto-generated cells

autoFlow?

optional autoFlow: AutoFlowDirection;

Defined in: types.ts:161

Direction of auto-flow when adding items

autoRows?

optional autoRows: number;

Defined in: types.ts:163

Default number of rows for auto-generated cells

backgroundColor?

optional backgroundColor: AnsiColorObject | AnsiColorFunction;

Defined in: types.ts:114

Global background color

Inherited from

Style.backgroundColor

border?

optional border: BorderStyle;

Defined in: types.ts:116

Border style configuration.

Inherited from

Style.border

borderColor?

optional borderColor: AnsiColorObject | AnsiColorFunction;

Defined in: types.ts:118

Global border color

Inherited from

Style.borderColor

columns

columns: number;

Defined in: types.ts:165

Number of columns in the grid

defaultTerminalWidth?

optional defaultTerminalWidth: number;

Defined in: types.ts:6

Default terminal width if detection fails (defaults to 80)

Inherited from

BaseRenderingOptions.defaultTerminalWidth;

fixedColumnWidths?

optional fixedColumnWidths: number[];

Defined in: types.ts:167

Fixed column widths

fixedRowHeights?

optional fixedRowHeights: number[];

Defined in: types.ts:169

Fixed row heights

foregroundColor?

optional foregroundColor: AnsiColorObject | AnsiColorFunction;

Defined in: types.ts:120

Global foreground color

Inherited from

Style.foregroundColor

gap?

optional gap: number;

Defined in: types.ts:8

Gap between cells

Inherited from

BaseRenderingOptions.gap;

maxWidth?

optional maxWidth: number;

Defined in: types.ts:10

Maximum width for the entire table/grid.

Inherited from

BaseRenderingOptions.maxWidth;

paddingLeft?

optional paddingLeft: number;

Defined in: types.ts:122

Global left padding

Inherited from

Style.paddingLeft

paddingRight?

optional paddingRight: number;

Defined in: types.ts:124

Global right padding

Inherited from

Style.paddingRight

rows?

optional rows: number;

Defined in: types.ts:171

Number of rows in the grid (0 for auto)

showBorders?

optional showBorders: boolean;

Defined in: types.ts:173

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

terminalWidth?

optional terminalWidth: number;

Defined in: types.ts:12

Explicit terminal width (overrides detected)

Inherited from

BaseRenderingOptions.terminalWidth;

truncate?

optional truncate: boolean | TruncateOptions;

Defined in: types.ts:15

Global truncation options/flag

Inherited from

BaseRenderingOptions.truncate;

wordWrap?

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

Defined in: types.ts:17

Global word wrap options/flag

Inherited from

BaseRenderingOptions.wordWrap;

Style

Defined in: types.ts:112

Base style properties applicable globally

Extended by

GridOptions

Properties

backgroundColor?

optional backgroundColor: AnsiColorObject | AnsiColorFunction;

Defined in: types.ts:114

Global background color

border?

optional border: BorderStyle;

Defined in: types.ts:116

Border style configuration.

borderColor?

optional borderColor: AnsiColorObject | AnsiColorFunction;

Defined in: types.ts:118

Global border color

foregroundColor?

optional foregroundColor: AnsiColorObject | AnsiColorFunction;

Defined in: types.ts:120

Global foreground color

paddingLeft?

optional paddingLeft: number;

Defined in: types.ts:122

Global left padding

paddingRight?

optional paddingRight: number;

Defined in: types.ts:124

Global right padding

TableItem

Defined in: types.ts:61

Extends

GridItem

Properties

backgroundColor?

optional backgroundColor: AnsiColorObject | AnsiColorFunction;

Defined in: types.ts:31

Background color for the entire cell (including padding)

Inherited from

GridItem.backgroundColor

colSpan?

optional colSpan: number;

Defined in: types.ts:33

Number of columns this cell spans

Inherited from

GridItem.colSpan

content

content: Content;

Defined in: types.ts:35

Content to display in the cell

Inherited from

GridItem.content

foregroundColor?

optional foregroundColor: AnsiColorObject | AnsiColorFunction;

Defined in: types.ts:37

Foreground color for the entire cell (including padding)

Inherited from

GridItem.foregroundColor

hAlign?

optional hAlign: HorizontalAlignment;

Defined in: types.ts:39

Horizontal alignment of the content

Inherited from

GridItem.hAlign

href?

optional href: string;

Defined in: types.ts:65

Optional URL for making the cell content a hyperlink.

maxWidth?

optional maxWidth: number;

Defined in: types.ts:41

Maximum width of the cell content before truncation

Inherited from

GridItem.maxWidth

rowSpan?

optional rowSpan: number;

Defined in: types.ts:43

Number of rows this cell spans

Inherited from

GridItem.rowSpan

truncate?

optional truncate: boolean | TruncateOptions;

Defined in: types.ts:46

Options for controlling how text is truncated when it exceeds maxWidth

Inherited from

GridItem.truncate

vAlign?

optional vAlign: VerticalAlignment;

Defined in: types.ts:48

Vertical alignment of the content

Inherited from

GridItem.vAlign

wordWrap?

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

Defined in: types.ts:50

Options for controlling word wrapping (takes precedence over truncate)

Inherited from

GridItem.wordWrap

TableOptions

Defined in: types.ts:130

Options specific to Table construction.

Extends

BaseRenderingOptions

Properties

columnWidths?

optional columnWidths: number | number[];

Defined in: types.ts:135

Fixed column widths. Can be a single number for all columns or an array for specific columns.

defaultTerminalWidth?

optional defaultTerminalWidth: number;

Defined in: types.ts:6

Default terminal width if detection fails (defaults to 80)

Inherited from

BaseRenderingOptions.defaultTerminalWidth;

gap?

optional gap: number;

Defined in: types.ts:8

Gap between cells

Inherited from

BaseRenderingOptions.gap;

maxWidth?

optional maxWidth: number;

Defined in: types.ts:10

Maximum width for the entire table/grid.

Inherited from

BaseRenderingOptions.maxWidth;

rowHeights?

optional rowHeights: number | number[];

Defined in: types.ts:140

Fixed row heights. Can be a single number for all rows or an array for specific rows.

showHeader?

optional showHeader: boolean;

Defined in: types.ts:142

Whether to show the header of the table

style?

optional style: Partial<Style>;

Defined in: types.ts:144

Global style options for the table

terminalWidth?

optional terminalWidth: number;

Defined in: types.ts:12

Explicit terminal width (overrides detected)

Inherited from

BaseRenderingOptions.terminalWidth;

transformTabToSpace?

optional transformTabToSpace: number;

Defined in: types.ts:146

Number of spaces for tab characters

truncate?

optional truncate: boolean | TruncateOptions;

Defined in: types.ts:15

Global truncation options/flag

Inherited from

BaseRenderingOptions.truncate;

wordWrap?

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

Defined in: types.ts:17

Global word wrap options/flag

Inherited from

BaseRenderingOptions.wordWrap;

Type Aliases

AutoFlowDirection

type AutoFlowDirection = "column" | "row";

Defined in: types.ts:151

BorderType

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

Defined in: types.ts:152

Content

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

Defined in: types.ts:27

GridCell

type GridCell = Content | GridItem;

Defined in: types.ts:54

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

HorizontalAlignment

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

Defined in: types.ts:150

TableCell

type TableCell = Content | TableItem;

Defined in: types.ts:68

VerticalAlignment

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

Defined in: types.ts:149

style

Variables

ASCII_BORDER

const ASCII_BORDER: BorderStyle;

Defined in: style.ts:132

ASCII border style using only ASCII characters.

BLOCK_BORDER

const BLOCK_BORDER: BorderStyle;

Defined in: style.ts:174

Block border style.

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.

INNER_HALF_BLOCK_BORDER

const INNER_HALF_BLOCK_BORDER: BorderStyle;

Defined in: style.ts:216

Inner half block border style.

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.

OUTER_HALF_BLOCK_BORDER

const OUTER_HALF_BLOCK_BORDER: BorderStyle;

Defined in: style.ts:195

Outer half block border style.

ROUNDED_BORDER

const ROUNDED_BORDER: BorderStyle;

Defined in: style.ts:69

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

THICK_BORDER

const THICK_BORDER: BorderStyle;

Defined in: style.ts:237

Thick line border style.

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