@visulima/tabular
Advanced tools
Create beautiful ASCII tables and grids with customizable borders, padding, and alignment. Supports Unicode, colors, and ANSI escape codes.
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
npm install @visulima/tabular
yarn add @visulima/tabular
pnpm add @visulima/tabular
The package provides two main classes for creating tables:
Table: High-level API for creating tables with headers and rowsGrid: Low-level API for more complex layouts and custom grid structuresThe 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 │
└──────────┴─────┴─────────────┘
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,
gap: 1, // Gap between cells
paddingLeft: 1,
paddingRight: 1,
});
// 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 │ Center │ Right │
│ │Multiline│ │
├─────────┤ ├────────┤
│ Bottom │ │ Bottom │
│ Left │ │ Right │
└─────────┴─────────┴────────┘
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:
open and close properties containing ANSI escape sequencesYou can combine background colors with:
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,
});
Defined in: grid.ts:65
A class that represents a grid layout with support for cell spanning, alignment, and borders
new Grid(options): Grid;
Defined in: grid.ts:90
Creates a new Grid instance
Configuration options for the grid
addItem(cell): this;
Defined in: grid.ts:138
Adds a single item to the grid
The cell to add
this
The grid instance for method chaining
addItems(items): this;
Defined in: grid.ts:148
Adds multiple items to the grid
GridCell[]
Array of items to add
this
The grid instance for method chaining
setBorder(border): this;
Defined in: grid.ts:178
Sets the border style for the grid
Border style configuration
this
The grid instance for method chaining
setColumns(columns): this;
Defined in: grid.ts:158
Sets the number of columns in the grid
number
Number of columns
this
The grid instance for method chaining
setMaxWidth(width): this;
Defined in: grid.ts:198
Sets the maximum width for the grid
number
Maximum width
this
The grid instance for method chaining
setRows(rows): this;
Defined in: grid.ts:168
Sets the number of rows in the grid
number
Number of rows
this
The grid instance for method chaining
setShowBorders(show): this;
Defined in: grid.ts:188
Sets whether borders should be shown
boolean
Whether to show borders
this
The grid instance for method chaining
toString(): string;
Defined in: grid.ts:207
Converts the grid to a string representation
string
A string containing the rendered grid
Defined in: table.ts:9
A versatile table generator for CLI applications.
new Table(options): Table;
Defined in: table.ts:24
Initializes a new Table instance.
TableOptions = {}
Configuration options for the table.
addRow(row): this;
Defined in: table.ts:60
Adds a single row to the table body.
Array of cells representing the row.
this
The Table instance for chaining.
addRows(...rows): this;
Defined in: table.ts:77
Adds multiple rows to the table body.
...TableCell[][]
Array of rows to add.
this
The Table instance for chaining.
setHeaders(headers): this;
Defined in: table.ts:43
Sets the header rows for the table. Replaces any existing headers.
Array of header rows OR a single header row.
this
The Table instance for chaining.
toString(): string;
Defined in: table.ts:93
Renders the table to a string.
string
The string representation of the table.
function createGrid(options): Grid;
Defined in: grid.ts:1416
Creates a new grid instance with the specified options
Configuration options for the grid
A new Grid instance
function createTable(options?): Table;
Defined in: table.ts:257
Creates a new Table instance.
Configuration options for the table.
A new Table instance.
Defined in: types.ts:70
char: string;
Defined in: types.ts:71
width: number;
Defined in: types.ts:72
Defined in: types.ts:78
Represents the style of the border for a table or grid.
bodyJoin: BorderComponent;
Defined in: types.ts:80
Box vertical character.
bodyLeft: BorderComponent;
Defined in: types.ts:82
Box vertical character.
bodyRight: BorderComponent;
Defined in: types.ts:84
Box vertical character.
bottomBody: BorderComponent;
Defined in: types.ts:86
Box horizontal character.
bottomJoin: BorderComponent;
Defined in: types.ts:88
Box bottom join character.
bottomLeft: BorderComponent;
Defined in: types.ts:90
Box bottom left character.
bottomRight: BorderComponent;
Defined in: types.ts:92
Box bottom right character.
joinBody: BorderComponent;
Defined in: types.ts:94
Box horizontal character.
joinJoin: BorderComponent;
Defined in: types.ts:96
Box horizontal join character.
joinLeft: BorderComponent;
Defined in: types.ts:98
Box left join character.
joinRight: BorderComponent;
Defined in: types.ts:100
Box right join character.
topBody: BorderComponent;
Defined in: types.ts:102
Box horizontal character.
topJoin: BorderComponent;
Defined in: types.ts:104
Box top join character.
topLeft: BorderComponent;
Defined in: types.ts:106
Box top left character.
topRight: BorderComponent;
Defined in: types.ts:108
Box top right character.
Defined in: types.ts:29
optional backgroundColor: AnsiColorObject | AnsiColorFunction;
Defined in: types.ts:31
Background color for the entire cell (including padding)
optional colSpan: number;
Defined in: types.ts:33
Number of columns this cell spans
content: Content;
Defined in: types.ts:35
Content to display in the cell
optional foregroundColor: AnsiColorObject | AnsiColorFunction;
Defined in: types.ts:37
Foreground color for the entire cell (including padding)
optional hAlign: HorizontalAlignment;
Defined in: types.ts:39
Horizontal alignment of the content
optional maxWidth: number;
Defined in: types.ts:41
Maximum width of the cell content before truncation
optional rowSpan: number;
Defined in: types.ts:43
Number of rows this cell spans
optional truncate: boolean | TruncateOptions;
Defined in: types.ts:46
Options for controlling how text is truncated when it exceeds maxWidth
optional vAlign: VerticalAlignment;
Defined in: types.ts:48
Vertical alignment of the content
optional wordWrap: boolean | Omit<WordWrapOptions, "width">;
Defined in: types.ts:50
Options for controlling word wrapping (takes precedence over truncate)
Defined in: types.ts:157
Options specific to Grid construction.
BaseRenderingOptions.Styleoptional autoColumns: number;
Defined in: types.ts:159
Default number of columns for auto-generated cells
optional autoFlow: AutoFlowDirection;
Defined in: types.ts:161
Direction of auto-flow when adding items
optional autoRows: number;
Defined in: types.ts:163
Default number of rows for auto-generated cells
optional backgroundColor: AnsiColorObject | AnsiColorFunction;
Defined in: types.ts:114
Global background color
optional border: BorderStyle;
Defined in: types.ts:116
Border style configuration.
optional borderColor: AnsiColorObject | AnsiColorFunction;
Defined in: types.ts:118
Global border color
columns: number;
Defined in: types.ts:165
Number of columns in the grid
optional defaultTerminalWidth: number;
Defined in: types.ts:6
Default terminal width if detection fails (defaults to 80)
BaseRenderingOptions.defaultTerminalWidth;
optional fixedColumnWidths: number[];
Defined in: types.ts:167
Fixed column widths
optional fixedRowHeights: number[];
Defined in: types.ts:169
Fixed row heights
optional foregroundColor: AnsiColorObject | AnsiColorFunction;
Defined in: types.ts:120
Global foreground color
optional gap: number;
Defined in: types.ts:8
Gap between cells
BaseRenderingOptions.gap;
optional maxWidth: number;
Defined in: types.ts:10
Maximum width for the entire table/grid.
BaseRenderingOptions.maxWidth;
optional paddingLeft: number;
Defined in: types.ts:122
Global left padding
optional paddingRight: number;
Defined in: types.ts:124
Global right padding
optional rows: number;
Defined in: types.ts:171
Number of rows in the grid (0 for auto)
optional showBorders: boolean;
Defined in: types.ts:173
Whether to show borders (only relevant if border is defined)
optional terminalWidth: number;
Defined in: types.ts:12
Explicit terminal width (overrides detected)
BaseRenderingOptions.terminalWidth;
optional truncate: boolean | TruncateOptions;
Defined in: types.ts:15
Global truncation options/flag
BaseRenderingOptions.truncate;
optional wordWrap: boolean | Omit<WordWrapOptions, "width">;
Defined in: types.ts:17
Global word wrap options/flag
BaseRenderingOptions.wordWrap;
Defined in: types.ts:112
Base style properties applicable globally
optional backgroundColor: AnsiColorObject | AnsiColorFunction;
Defined in: types.ts:114
Global background color
optional border: BorderStyle;
Defined in: types.ts:116
Border style configuration.
optional borderColor: AnsiColorObject | AnsiColorFunction;
Defined in: types.ts:118
Global border color
optional foregroundColor: AnsiColorObject | AnsiColorFunction;
Defined in: types.ts:120
Global foreground color
optional paddingLeft: number;
Defined in: types.ts:122
Global left padding
optional paddingRight: number;
Defined in: types.ts:124
Global right padding
Defined in: types.ts:61
optional backgroundColor: AnsiColorObject | AnsiColorFunction;
Defined in: types.ts:31
Background color for the entire cell (including padding)
optional colSpan: number;
Defined in: types.ts:33
Number of columns this cell spans
content: Content;
Defined in: types.ts:35
Content to display in the cell
optional foregroundColor: AnsiColorObject | AnsiColorFunction;
Defined in: types.ts:37
Foreground color for the entire cell (including padding)
optional hAlign: HorizontalAlignment;
Defined in: types.ts:39
Horizontal alignment of the content
optional href: string;
Defined in: types.ts:65
Optional URL for making the cell content a hyperlink.
optional maxWidth: number;
Defined in: types.ts:41
Maximum width of the cell content before truncation
optional rowSpan: number;
Defined in: types.ts:43
Number of rows this cell spans
optional truncate: boolean | TruncateOptions;
Defined in: types.ts:46
Options for controlling how text is truncated when it exceeds maxWidth
optional vAlign: VerticalAlignment;
Defined in: types.ts:48
Vertical alignment of the content
optional wordWrap: boolean | Omit<WordWrapOptions, "width">;
Defined in: types.ts:50
Options for controlling word wrapping (takes precedence over truncate)
Defined in: types.ts:130
Options specific to Table construction.
BaseRenderingOptionsoptional 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.
optional defaultTerminalWidth: number;
Defined in: types.ts:6
Default terminal width if detection fails (defaults to 80)
BaseRenderingOptions.defaultTerminalWidth;
optional gap: number;
Defined in: types.ts:8
Gap between cells
BaseRenderingOptions.gap;
optional maxWidth: number;
Defined in: types.ts:10
Maximum width for the entire table/grid.
BaseRenderingOptions.maxWidth;
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.
optional showHeader: boolean;
Defined in: types.ts:142
Whether to show the header of the table
optional style: Partial<Style>;
Defined in: types.ts:144
Global style options for the table
optional terminalWidth: number;
Defined in: types.ts:12
Explicit terminal width (overrides detected)
BaseRenderingOptions.terminalWidth;
optional transformTabToSpace: number;
Defined in: types.ts:146
Number of spaces for tab characters
optional truncate: boolean | TruncateOptions;
Defined in: types.ts:15
Global truncation options/flag
BaseRenderingOptions.truncate;
optional wordWrap: boolean | Omit<WordWrapOptions, "width">;
Defined in: types.ts:17
Global word wrap options/flag
BaseRenderingOptions.wordWrap;
type AutoFlowDirection = "column" | "row";
Defined in: types.ts:151
type BorderType = "bottom" | "middle" | "top";
Defined in: types.ts:152
type Content = bigint | boolean | number | string | null | undefined;
Defined in: types.ts:27
type GridCell = Content | GridItem;
Defined in: types.ts:54
Input type for a cell, can be primitive or an options object
type HorizontalAlignment = "center" | "left" | "right";
Defined in: types.ts:150
type TableCell = Content | TableItem;
Defined in: types.ts:68
type VerticalAlignment = "bottom" | "middle" | "top";
Defined in: types.ts:149
const ASCII_BORDER: BorderStyle;
Defined in: style.ts:132
ASCII border style using only ASCII characters.
const BLOCK_BORDER: BorderStyle;
Defined in: style.ts:174
Block border style.
const DEFAULT_BORDER: BorderStyle;
Defined in: style.ts:6
Default border style using standard box-drawing characters.
const DOTS_BORDER: BorderStyle;
Defined in: style.ts:90
Border style using dots for the border.
const DOUBLE_BORDER: BorderStyle;
Defined in: style.ts:48
Double-line border style using Unicode box-drawing characters.
const INNER_HALF_BLOCK_BORDER: BorderStyle;
Defined in: style.ts:216
Inner half block border style.
const MARKDOWN_BORDER: BorderStyle;
Defined in: style.ts:111
Border style using Markdown syntax.
const MINIMAL_BORDER: BorderStyle;
Defined in: style.ts:27
Minimal border style using only horizontal lines.
const NO_BORDER: BorderStyle;
Defined in: style.ts:153
No border style.
const OUTER_HALF_BLOCK_BORDER: BorderStyle;
Defined in: style.ts:195
Outer half block border style.
const ROUNDED_BORDER: BorderStyle;
Defined in: style.ts:69
Border style with rounded corners using Unicode box-drawing characters.
const THICK_BORDER: BorderStyle;
Defined in: style.ts:237
Thick line border style.
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.
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.
The visulima tabular is open-sourced software licensed under the MIT
FAQs
Create beautiful ASCII tables and grids with customizable borders, padding, and alignment. Supports Unicode, colors, and ANSI escape codes.
The npm package @visulima/tabular receives a total of 179 weekly downloads. As such, @visulima/tabular popularity was classified as not popular.
We found that @visulima/tabular demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket Fix 2.0 brings targeted CVE remediation, smarter upgrade planning, and broader ecosystem support to help developers get to zero alerts.
Security News
Socket CEO Feross Aboukhadijeh joins Risky Business Weekly to unpack recent npm phishing attacks, their limited impact, and the risks if attackers get smarter.
Product
Socket’s new Tier 1 Reachability filters out up to 80% of irrelevant CVEs, so security teams can focus on the vulnerabilities that matter.