tessl/npm-cli-table3

Pretty unicode tables for the command line with advanced features like spanning, alignment, and ANSI color support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Styling and Layout

Name: tessl/npm-cli-table3
Author: tessl

Comprehensive styling system with customizable border characters, colors, padding, alignment, and layout options for creating visually appealing tables.

Capabilities

Style Configuration

Global styling options that affect the entire table appearance.

interface StyleOptions {
  /** Left padding in spaces */
  'padding-left': number;
  /** Right padding in spaces */
  'padding-right': number;
  /** Color array for header text */
  head: string[];
  /** Color array for border characters */
  border: string[];
  /** Enable compact mode (reduced vertical spacing) */
  compact: boolean;
}

Usage Examples:

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

// Basic styling
const table = new Table({
  style: {
    'padding-left': 2,
    'padding-right': 2,
    head: ['cyan', 'bold'],
    border: ['gray'],
    compact: true
  }
});

// No styling (clean output)
const cleanTable = new Table({
  style: {
    head: [],
    border: []
  }
});

Border Character Customization

Complete control over all border characters used in table rendering.

chars?: Partial<Record<CharName, string>>;

type CharName = 
  | 'top' | 'top-mid' | 'top-left' | 'top-right'
  | 'bottom' | 'bottom-mid' | 'bottom-left' | 'bottom-right'
  | 'left' | 'left-mid' | 'mid' | 'mid-mid' 
  | 'right' | 'right-mid' | 'middle';

Usage Examples:

// ASCII-only borders
const asciiTable = 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': '|'
  }
});

// Double-line borders
const doubleTable = 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': '║'
  }
});

// Rounded corners
const roundedTable = 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': '│'
  }
});

Color Support

Integration with @colors/colors for text and border coloring.

style: {
  head: string[];
  border: string[];
}

Usage Examples:

const colors = require('@colors/colors/safe');

// Table with colored headers and borders
const coloredTable = new Table({
  head: ['Name', 'Status', 'Score'],
  style: {
    head: ['cyan', 'bold'],
    border: ['gray']
  }
});

// Custom colors in cells
coloredTable.push([
  'Alice',
  colors.green('Active'),
  colors.yellow('95')
]);

// Multiple color effects
const fancyTable = new Table({
  style: {
    head: ['red', 'bold', 'underline'],
    border: ['cyan', 'dim']
  }
});

Padding Configuration

Control cell padding for content spacing.

'padding-left': number;
'padding-right': number;

Usage Examples:

// Tight padding
const compactTable = new Table({
  style: {
    'padding-left': 0,
    'padding-right': 0
  }
});

// Generous padding
const spaciousTable = new Table({
  style: {
    'padding-left': 3,
    'padding-right': 3
  }
});

// Asymmetric padding
const asymmetricTable = new Table({
  style: {
    'padding-left': 1,
    'padding-right': 4
  }
});

Layout Modes

Control table layout behavior and spacing.

compact: boolean;

Usage Examples:

// Compact mode (no extra spacing between rows)
const compactTable = new Table({
  style: { compact: true }
});

// Standard mode (with row separators)
const standardTable = new Table({
  style: { compact: false }
});

Text Alignment

Global alignment settings for table content.

colAligns?: HorizontalAlignment[];
rowAligns?: VerticalAlignment[];

type HorizontalAlignment = 'left' | 'center' | 'right';
type VerticalAlignment = 'top' | 'center' | 'bottom';

Usage Examples:

// Column-specific alignment
const alignedTable = new Table({
  head: ['Product', 'Price', 'Quantity', 'Total'],
  colAligns: ['left', 'right', 'center', 'right']
});

// Row-specific vertical alignment
const verticalTable = new Table({
  rowAligns: ['top', 'center', 'bottom']
});

Predefined Styles

Minimal Style

Clean table without colors or extra formatting.

const minimalTable = new Table({
  style: {
    'padding-left': 1,
    'padding-right': 1,
    head: [],
    border: [],
    compact: false
  }
});

Corporate Style

Professional appearance suitable for reports.

const corporateTable = new Table({
  style: {
    'padding-left': 2,
    'padding-right': 2,
    head: ['bold'],
    border: ['gray'],
    compact: true
  },
  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': '│'
  }
});

Colorful Style

Vibrant appearance with colors and effects.

const colorfulTable = new Table({
  style: {
    'padding-left': 1,
    'padding-right': 1,
    head: ['cyan', 'bold'],
    border: ['magenta'],
    compact: false
  }
});

Advanced Styling Examples

Dashboard Table

const dashboardTable = new Table({
  head: ['Metric', 'Current', 'Target', 'Status'],
  colWidths: [20, 15, 15, 12],
  colAligns: ['left', 'right', 'right', 'center'],
  style: {
    head: ['cyan', 'bold'],
    border: ['gray'],
    compact: true
  }
});

dashboardTable.push([
  'Revenue',
  colors.green('$125K'),
  '$120K',
  colors.green('✓')
]);

dashboardTable.push([
  'Customer Satisfaction',
  colors.yellow('8.2/10'),
  '8.5/10',
  colors.yellow('~')
]);

Report Table

const reportTable = new Table({
  head: ['Department', 'Budget', 'Spent', 'Remaining', '% Used'],
  colWidths: [15, 12, 12, 12, 8],
  colAligns: ['left', 'right', 'right', 'right', 'center'],
  style: {
    'padding-left': 2,
    'padding-right': 2,
    head: ['bold', 'underline'],
    border: [],
    compact: false
  },
  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': '│'
  }
});

Debug Table

const debugTable = new Table({
  head: ['Variable', 'Type', 'Value', 'Memory'],
  style: {
    head: ['red', 'bold'],
    border: ['dim'],
    compact: true
  },
  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 Inheritance

Styles cascade from table level to cell level:

Default styles - Library defaults
Table styles - Applied to entire table
Cell styles - Override table styles for specific cells

const table = new Table({
  // Table-level styles
  style: {
    'padding-left': 2,
    head: ['blue']
  }
});

table.push([
  'Normal cell',  // Uses table padding and colors
  {
    content: 'Custom cell',
    style: {
      'padding-left': 4,  // Overrides table padding
      head: ['red']       // Overrides table color
    }
  }
]);

Default Character Set

The library uses Unicode box-drawing characters by default:

const defaultChars = {
  'top': '─',           // Horizontal line
  'top-mid': '┬',       // T-junction down
  'top-left': '┌',      // Top-left corner
  'top-right': '┐',     // Top-right corner
  'bottom': '─',        // Horizontal line
  'bottom-mid': '┴',    // T-junction up
  'bottom-left': '└',   // Bottom-left corner
  'bottom-right': '┘',  // Bottom-right corner
  'left': '│',          // Vertical line
  'left-mid': '├',      // T-junction right
  'mid': '─',           // Horizontal line
  'mid-mid': '┼',       // Cross junction
  'right': '│',         // Vertical line
  'right-mid': '┤',     // T-junction left
  'middle': '│'         // Vertical line
};

Install with Tessl CLI