or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-cli-table

Pretty unicode tables for the CLI with customizable styling and layout options

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/cli-table@0.3.x

To install, run

npx @tessl/cli install tessl/npm-cli-table@0.3.0

index.mddocs/

CLI Table

CLI Table is a Node.js library that renders unicode-aided tables for command-line interfaces. It provides a Table class that extends Array functionality with customizable table rendering capabilities, supporting horizontal, vertical, and cross table layouts with extensive styling options.

Package Information

  • Package Name: cli-table
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install cli-table

Core Imports

const Table = require('cli-table');

Note: This package uses CommonJS exports. ES module imports are not supported.

Basic Usage

const Table = require('cli-table');

// Create a basic horizontal table
const table = new Table({
  head: ['Name', 'Age', 'City'],
  colWidths: [10, 5, 15]
});

table.push(
  ['Alice', 25, 'New York'],
  ['Bob', 30, 'San Francisco']
);

console.log(table.toString());

Architecture

CLI Table consists of:

  • Table Class: Main constructor extending Array.prototype for array-like functionality
  • Options System: Comprehensive configuration for characters, styling, dimensions, and alignment
  • Rendering Engine: Unicode-aware string rendering with ANSI color support
  • Layout Types: Support for horizontal (row-based), vertical (key-value), and cross (matrix) layouts

Capabilities

Table Constructor

Creates a new Table instance with customizable options for rendering unicode tables.

/**
 * Table constructor
 * @param {Object} options - Configuration options for table appearance and behavior
 * @returns {Table} New Table instance with Array-like functionality
 */
function Table(options);

interface TableOptions {
  /** Unicode characters for table borders and intersections */
  chars?: {
    'top'?: string;
    'top-mid'?: string;
    'top-left'?: string;
    'top-right'?: string;
    'bottom'?: string;
    'bottom-mid'?: string;
    'bottom-left'?: string;
    'bottom-right'?: string;
    'left'?: string;
    'left-mid'?: string;
    'mid'?: string;
    'mid-mid'?: string;
    'right'?: string;
    'right-mid'?: string;
    'middle'?: string;
  };
  /** Character used for text truncation */
  truncate?: string;
  /** Array of column widths in characters */
  colWidths?: number[];
  /** Array of column alignments ('left', 'right', 'middle') */
  colAligns?: ('left' | 'right' | 'middle')[];
  /** Styling configuration */
  style?: {
    'padding-left'?: number;
    'padding-right'?: number;
    /** Colors for header row (colors.js style names) */
    head?: string[];
    /** Colors for border characters */
    border?: string[];
    /** Whether to use compact mode (reduces separator lines between rows) */
    compact?: boolean;
  };
  /** Header row values */
  head?: any[];
  /** Initial table rows (optional) */
  rows?: any[][];
}

Usage Examples:

// Basic table with headers
const table = new Table({
  head: ['ID', 'Name', 'Status'],
  colWidths: [5, 20, 10]
});

// Table with custom styling
const styledTable = new Table({
  head: ['Item', 'Count'],
  style: {
    head: ['red'],
    border: ['grey'],
    'padding-left': 2,
    'padding-right': 2
  }
});

// Table with custom border characters
const customTable = new Table({
  chars: {
    'top': '═', 'top-mid': '╤', 'top-left': '╔', 'top-right': '╗',
    'bottom': '═', 'bottom-mid': '╧', 'bottom-left': '╚', 'bottom-right': '╝',
    'left': '║', 'left-mid': '╟', 'mid': '─', 'mid-mid': '┼',
    'right': '║', 'right-mid': '╢', 'middle': '│'
  }
});

// Initialize with rows in constructor
const prefilledTable = new Table({
  head: ['Name', 'Age'],
  rows: [
    ['Alice', 25],
    ['Bob', 30]
  ]
});

Table Rendering

Converts the table data to a formatted string representation.

/**
 * Renders table to string representation
 * @returns {string} Formatted table as a string
 */
Table.prototype.toString();

/**
 * Renders table to string representation
 * NOTE: The render() method alias is not properly implemented in this version
 * Use toString() instead for reliable rendering
 * @returns {string} Formatted table as a string
 */
// Table.prototype.render(); // Not properly implemented - use toString()

Usage Examples:

const table = new Table({
  head: ['Name', 'Score']
});

table.push(['Alice', 95], ['Bob', 87]);

// Render to string
const tableString = table.toString();
console.log(tableString);
// Note: render() method is not properly implemented in this version
// Use toString() for reliable rendering

Table Width Property

Gets the rendered width of the table in characters.

/**
 * Width getter property
 * @returns {number} Width of the rendered table in characters
 */
Table.prototype.width;

Usage Example:

const table = new Table({
  head: ['A', 'B', 'C'],
  colWidths: [10, 15, 20]
});

table.push(['data1', 'data2', 'data3']);

console.log(`Table width: ${table.width} characters`);

Version Information

Access the library version string.

/**
 * Library version string
 * Note: This returns "0.0.1" regardless of the actual package version
 * @type {string}
 */
Table.version;

Usage Example:

const Table = require('cli-table');
console.log(`Using CLI Table version: ${Table.version}`); // Will output "0.0.1"

Array Methods

Table instances inherit all Array methods for manipulating table data.

/**
 * Add rows to the end of the table
 * @param {...any[]} rows - Row data to add
 * @returns {number} New length of the table
 */
Table.prototype.push(...rows);

/**
 * Add rows to the beginning of the table
 * @param {...any[]} rows - Row data to add
 * @returns {number} New length of the table
 */
Table.prototype.unshift(...rows);

/**
 * Insert/remove rows at specific position
 * @param {number} start - Starting index
 * @param {number} deleteCount - Number of elements to remove
 * @param {...any[]} items - Items to insert
 * @returns {any[]} Array of removed elements
 */
Table.prototype.splice(start, deleteCount, ...items);

/**
 * Number of rows in the table
 * @type {number}
 */
Table.prototype.length;

Usage Examples:

const table = new Table({
  head: ['Name', 'Age']
});

// Add rows at the end
table.push(['Alice', 25]);
table.push(['Bob', 30], ['Charlie', 35]);

// Add rows at the beginning
table.unshift(['Header Row', 'Data']);

// Insert row at specific position
table.splice(1, 0, ['Inserted', 'Row']);

// Remove and replace rows
const removed = table.splice(2, 1, ['New', 'Data']);

console.log(`Table has ${table.length} rows`);

Table Layout Types

Horizontal Tables

Standard tabular layout with headers and data rows.

Usage Example:

const table = new Table({
  head: ['Product', 'Price', 'Stock'],
  colWidths: [15, 10, 8]
});

table.push(
  ['Laptop', '$999', '5'],
  ['Mouse', '$25', '50'],
  ['Keyboard', '$75', '25']
);

console.log(table.toString());

Vertical Tables

Key-value pair layout where each row is an object with a single key-value pair.

Usage Example:

const table = new Table();

table.push(
  { 'Name': 'John Doe' },
  { 'Age': '30' },
  { 'City': 'New York' },
  { 'Occupation': 'Developer' }
);

console.log(table.toString());

Cross Tables

Matrix layout combining vertical headers with horizontal data arrays.

Usage Example:

const table = new Table({
  head: ['', 'Q1', 'Q2', 'Q3', 'Q4']
});

table.push(
  { 'Sales': ['$10k', '$15k', '$12k', '$18k'] },
  { 'Costs': ['$5k', '$7k', '$6k', '$8k'] },
  { 'Profit': ['$5k', '$8k', '$6k', '$10k'] }
);

console.log(table.toString());

Compact Mode

When compact is set to true in the style options, the table reduces the number of separator lines between rows for a more condensed appearance.

Usage Example:

// Regular table with separators between rows
const regularTable = new Table({
  head: ['Name', 'Score'],
  style: { compact: false }
});
regularTable.push(['Alice', '95'], ['Bob', '87']);

// Compact table with fewer separators
const compactTable = new Table({
  head: ['Name', 'Score'],
  style: { compact: true }
});
compactTable.push(['Alice', '95'], ['Bob', '87']);

console.log('Regular:');
console.log(regularTable.toString());
console.log('\nCompact:');
console.log(compactTable.toString());

Advanced Usage: Empty Rows and Custom Styling

Tables can include empty rows for spacing and fully customized border characters.

Usage Example:

// Table with empty rows for spacing
const table = new Table({
  head: ['Rel', 'Change', 'By', 'When'],
  colWidths: [6, 21, 25, 17]
});

table.push(
  ['v0.1', 'Testing something cool', 'rauchg@gmail.com', '7 minutes ago'],
  ['v0.1', 'Testing something cool', 'rauchg@gmail.com', '8 minutes ago'],
  [], // Empty row for spacing
  ['v0.2', 'Another feature', 'dev@example.com', '1 hour ago']
);

console.log(table.toString());

// Borderless table with minimal styling
const borderlessTable = new Table({
  chars: { 
    'top': '', 'top-mid': '', 'top-left': '', 'top-right': '',
    'bottom': '', 'bottom-mid': '', 'bottom-left': '', 'bottom-right': '',
    'left': '', 'left-mid': '', 'mid': '', 'mid-mid': '',
    'right': '', 'right-mid': '', 'middle': ' '
  },
  style: { 'padding-left': 0, 'padding-right': 0 }
});

borderlessTable.push(
  ['foo', 'bar', 'baz'],
  ['frobnicate', 'bar', 'quuz']
);

console.log(borderlessTable.toString());
// Output:
// foo        bar baz
// frobnicate bar quuz

Types

/**
 * Table constructor function and class
 */
declare class Table extends Array {
  constructor(options?: TableOptions);
  
  /** Width of the rendered table in characters */
  readonly width: number;
  
  /** Render table to string */
  toString(): string;
  
  /** Render table to string (alias for toString) */
  render(): string;
  
  /** Library version string */
  static version: string;
}

/**
 * Table configuration options
 */
interface TableOptions {
  chars?: {
    'top'?: string;
    'top-mid'?: string;
    'top-left'?: string;
    'top-right'?: string;
    'bottom'?: string;
    'bottom-mid'?: string;
    'bottom-left'?: string;
    'bottom-right'?: string;
    'left'?: string;
    'left-mid'?: string;
    'mid'?: string;
    'mid-mid'?: string;
    'right'?: string;
    'right-mid'?: string;
    'middle'?: string;
  };
  truncate?: string;
  colWidths?: number[];
  colAligns?: ('left' | 'right' | 'middle')[];
  style?: {
    'padding-left'?: number;
    'padding-right'?: number;
    head?: string[];
    border?: string[];
    compact?: boolean;
  };
  head?: any[];
  rows?: any[][];
}