Need help with table?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

gajus
592 Stars 71 Forks Other 247 Commits 21 Opened issues

Description

Formats data into a string table.

Services available

!
?

Need anything else?

Contributors list

Table

Produces a string that represents array data in a text table.

Travis build status Coveralls NPM version Canonical Code Style Twitter Follow

Demo of table displaying a list of missions to the Moon.

Features

  • Works with strings containing fullwidth characters.
  • Works with strings containing ANSI escape codes.
  • Configurable border characters.
  • Configurable content alignment per column.
  • Configurable content padding per column.
  • Configurable column width.
  • Text wrapping.

Install

npm install table

Buy Me A Coffee Become a Patron

Usage

import { table } from 'table';

// Using commonjs? // const { table } = require('table');

const data = [ ['0A', '0B', '0C'], ['1A', '1B', '1C'], ['2A', '2B', '2C'] ];

console.log(table(data));

╔════╤════╤════╗
║ 0A │ 0B │ 0C ║
╟────┼────┼────╢
║ 1A │ 1B │ 1C ║
╟────┼────┼────╢
║ 2A │ 2B │ 2C ║
╚════╧════╧════╝

API

table

Returns the string in the table format

Parameters: - data: The data to display - Type:

any[][]
- Required:
true
  • config: Table configuration
    • Type:
      object
    • Required:
      false

config.border

Type:

{ [type: string]: string }
\ Default:
honeywell
template

Custom borders. The keys are any of: -

topLeft
,
topRight
,
topBody
,
topJoin
-
bottomLeft
,
bottomRight
,
bottomBody
,
bottomJoin
-
joinLeft
,
joinRight
,
joinBody
,
joinJoin
-
bodyLeft
,
bodyRight
,
bodyJoin
-
headerJoin
const data = [
  ['0A', '0B', '0C'],
  ['1A', '1B', '1C'],
  ['2A', '2B', '2C']
];

const config = { border: { topBody: , topJoin: , topLeft: , topRight: ,

bottomBody: `─`,
bottomJoin: `┴`,
bottomLeft: `└`,
bottomRight: `┘`,

bodyLeft: `│`,
bodyRight: `│`,
bodyJoin: `│`,

joinBody: `─`,
joinLeft: `├`,
joinRight: `┤`,
joinJoin: `┼`

} };

console.log(table(data, config));

┌────┬────┬────┐
│ 0A │ 0B │ 0C │
├────┼────┼────┤
│ 1A │ 1B │ 1C │
├────┼────┼────┤
│ 2A │ 2B │ 2C │
└────┴────┴────┘

config.drawVerticalLine

Type:

(lineIndex: number, columnCount: number) => boolean
\ Default:
() => true

It is used to tell whether to draw a vertical line. This callback is called for each vertical border of the table. If the table has

n
columns, then the
index
parameter is alternatively received all numbers in range
[0, n]
inclusively.
const data = [
  ['0A', '0B', '0C'],
  ['1A', '1B', '1C'],
  ['2A', '2B', '2C'],
  ['3A', '3B', '3C'],
  ['4A', '4B', '4C']
];

const config = { drawVerticalLine: (lineIndex, columnCount) => { return lineIndex === 0 || lineIndex === columnCount; } };

console.log(table(data, config));

╔════════════╗
║ 0A  0B  0C ║
╟────────────╢
║ 1A  1B  1C ║
╟────────────╢
║ 2A  2B  2C ║
╟────────────╢
║ 3A  3B  3C ║
╟────────────╢
║ 4A  4B  4C ║
╚════════════╝

config.drawHorizontalLine

Type:

(lineIndex: number, rowCount: number) => boolean
\ Default:
() => true

It is used to tell whether to draw a horizontal line. This callback is called for each horizontal border of the table. If the table has

n
rows, then the
index
parameter is alternatively received all numbers in range
[0, n]
inclusively. If the table has
n
rows and contains the header, then the range will be
[0, n+1]
inclusively.
const data = [
  ['0A', '0B', '0C'],
  ['1A', '1B', '1C'],
  ['2A', '2B', '2C'],
  ['3A', '3B', '3C'],
  ['4A', '4B', '4C']
];

const config = { drawHorizontalLine: (lineIndex, rowCount) => { return lineIndex === 0 || lineIndex === 1 || lineIndex === rowCount - 1 || lineIndex === rowCount; } };

console.log(table(data, config));

╔════╤════╤════╗
║ 0A │ 0B │ 0C ║
╟────┼────┼────╢
║ 1A │ 1B │ 1C ║
║ 2A │ 2B │ 2C ║
║ 3A │ 3B │ 3C ║
╟────┼────┼────╢
║ 4A │ 4B │ 4C ║
╚════╧════╧════╝

config.singleLine

Type:

boolean
\ Default:
false

If

true
, horizontal lines inside the table are not drawn. This option also overrides the
config.drawHorizontalLine
if specified.
const data = [
  ['-rw-r--r--', '1', 'pandorym', 'staff', '1529', 'May 23 11:25', 'LICENSE'],
  ['-rw-r--r--', '1', 'pandorym', 'staff', '16327', 'May 23 11:58', 'README.md'],
  ['drwxr-xr-x', '76', 'pandorym', 'staff', '2432', 'May 23 12:02', 'dist'],
  ['drwxr-xr-x', '634', 'pandorym', 'staff', '20288', 'May 23 11:54', 'node_modules'],
  ['-rw-r--r--', '1,', 'pandorym', 'staff', '525688', 'May 23 11:52', 'package-lock.json'],
  ['[email protected]', '1', 'pandorym', 'staff', '2440', 'May 23 11:25', 'package.json'],
  ['drwxr-xr-x', '27', 'pandorym', 'staff', '864', 'May 23 11:25', 'src'],
  ['drwxr-xr-x', '20', 'pandorym', 'staff', '640', 'May 23 11:25', 'test'],
];

const config = { singleLine: true };

console.log(table(data, config));

╔═════════════╤═════╤══════════╤═══════╤════════╤══════════════╤═══════════════════╗
║ -rw-r--r--  │ 1   │ pandorym │ staff │ 1529   │ May 23 11:25 │ LICENSE           ║
║ -rw-r--r--  │ 1   │ pandorym │ staff │ 16327  │ May 23 11:58 │ README.md         ║
║ drwxr-xr-x  │ 76  │ pandorym │ staff │ 2432   │ May 23 12:02 │ dist              ║
║ drwxr-xr-x  │ 634 │ pandorym │ staff │ 20288  │ May 23 11:54 │ node_modules      ║
║ -rw-r--r--  │ 1,  │ pandorym │ staff │ 525688 │ May 23 11:52 │ package-lock.json ║
║ [email protected] │ 1   │ pandorym │ staff │ 2440   │ May 23 11:25 │ package.json      ║
║ drwxr-xr-x  │ 27  │ pandorym │ staff │ 864    │ May 23 11:25 │ src               ║
║ drwxr-xr-x  │ 20  │ pandorym │ staff │ 640    │ May 23 11:25 │ test              ║
╚═════════════╧═════╧══════════╧═══════╧════════╧══════════════╧═══════════════════╝

config.columns

Type:

Column[] | { [columnIndex: number]: Column }

Column specific configurations.

config.columns[*].width

Type:

number
\ Default: the maximum cell widths of the column

Column width (excluding the paddings).

const data = [
  ['0A', '0B', '0C'],
  ['1A', '1B', '1C'],
  ['2A', '2B', '2C']
];

const config = { columns: { 1: { width: 10 } } };

console.log(table(data, config));

╔════╤════════════╤════╗
║ 0A │ 0B         │ 0C ║
╟────┼────────────┼────╢
║ 1A │ 1B         │ 1C ║
╟────┼────────────┼────╢
║ 2A │ 2B         │ 2C ║
╚════╧════════════╧════╝

config.columns[*].alignment

Type:

'center' | 'justify' | 'left' | 'right'
\ Default:
'left'

Cell content horizontal alignment

const data = [
  ['0A', '0B', '0C', '0D 0E 0F'],
  ['1A', '1B', '1C', '1D 1E 1F'],
  ['2A', '2B', '2C', '2D 2E 2F'],
];

const config = { columnDefault: { width: 10, }, columns: [ { alignment: 'left' }, { alignment: 'center' }, { alignment: 'right' }, { alignment: 'justify' } ], };

console.log(table(data, config));

╔════════════╤════════════╤════════════╤════════════╗
║ 0A         │     0B     │         0C │ 0D  0E  0F ║
╟────────────┼────────────┼────────────┼────────────╢
║ 1A         │     1B     │         1C │ 1D  1E  1F ║
╟────────────┼────────────┼────────────┼────────────╢
║ 2A         │     2B     │         2C │ 2D  2E  2F ║
╚════════════╧════════════╧════════════╧════════════╝

config.columns[*].verticalAlignment

Type:

'top' | 'middle' | 'bottom'
\ Default:
'top'

Cell content vertical alignment

const data = [
  ['A', 'B', 'C', 'DEF'],
];

const config = { columnDefault: { width: 1, }, columns: [ { verticalAlignment: 'top' }, { verticalAlignment: 'middle' }, { verticalAlignment: 'bottom' }, ], };

console.log(table(data, config));

╔═══╤═══╤═══╤═══╗
║ A │   │   │ D ║
║   │ B │   │ E ║
║   │   │ C │ F ║
╚═══╧═══╧═══╧═══╝

config.columns[*].paddingLeft

Type:

number
\ Default:
1

The number of whitespaces used to pad the content on the left.

config.columns[*].paddingRight

Type:

number
\ Default:
1

The number of whitespaces used to pad the content on the right.

The

paddingLeft
and
paddingRight
options do not count on the column width. So the column has
width = 5
,
paddingLeft = 2
and
paddingRight = 2
will have the total width is
9
.
const data = [
  ['0A', 'AABBCC', '0C'],
  ['1A', '1B', '1C'],
  ['2A', '2B', '2C']
];

const config = { columns: [ { paddingLeft: 3 }, { width: 2, paddingRight: 3 } ] };

console.log(table(data, config));

╔══════╤══════╤════╗
║   0A │ AA   │ 0C ║
║      │ BB   │    ║
║      │ CC   │    ║
╟──────┼──────┼────╢
║   1A │ 1B   │ 1C ║
╟──────┼──────┼────╢
║   2A │ 2B   │ 2C ║
╚══════╧══════╧════╝

config.columns[*].truncate

Type:

number
\ Default:
Infinity

The number of characters is which the content will be truncated. To handle a content that overflows the container width,

table
package implements text wrapping. However, sometimes you may want to truncate content that is too long to be displayed in the table.
const data = [
  ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
];

const config = { columns: [ { width: 20, truncate: 100 } ] };

console.log(table(data, config));

╔══════════════════════╗
║ Lorem ipsum dolor si ║
║ t amet, consectetur  ║
║ adipiscing elit. Pha ║
║ sellus pulvinar nibh ║
║ sed mauris convall…  ║
╚══════════════════════╝

config.columns[*].wrapWord

Type:

boolean
\ Default:
false

The

table
package implements auto text wrapping, i.e., text that has the width greater than the container width will be separated into multiple lines at the nearest space or one of the special characters:
\|/_.,;-
.

When

wrapWord
is
false
:
const data = [
    ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
];

const config = { columns: [ { width: 20 } ] };

console.log(table(data, config));

╔══════════════════════╗
║ Lorem ipsum dolor si ║
║ t amet, consectetur  ║
║ adipiscing elit. Pha ║
║ sellus pulvinar nibh ║
║ sed mauris convallis ║
║ dapibus. Nunc venena ║
║ tis tempus nulla sit ║
║ amet viverra.        ║
╚══════════════════════╝

When

wrapWord
is
true
:
╔══════════════════════╗
║ Lorem ipsum dolor    ║
║ sit amet,            ║
║ consectetur          ║
║ adipiscing elit.     ║
║ Phasellus pulvinar   ║
║ nibh sed mauris      ║
║ convallis dapibus.   ║
║ Nunc venenatis       ║
║ tempus nulla sit     ║
║ amet viverra.        ║
╚══════════════════════╝

config.columnDefault

Type:

Column
\ Default:
{}

The default configuration for all columns. Column-specific settings will overwrite the default values.

config.header

Type:

object

Header configuration.

The header configuration inherits the most of the column's, except: -

content
{string}: the header content. -
width:
calculate based on the content width automatically. -
alignment:
center
be default. -
verticalAlignment:
is not supported. -
config.border.topJoin
will be
config.border.topBody
for prettier.
const data = [
      ['0A', '0B', '0C'],
      ['1A', '1B', '1C'],
      ['2A', '2B', '2C'],
    ];

const config = { columnDefault: { width: 10, }, header: { alignment: 'center', content: 'THE HEADER\nThis is the table about something', }, }

console.log(table(data, config));

╔══════════════════════════════════════╗
║              THE HEADER              ║
║  This is the table about something   ║
╟────────────┬────────────┬────────────╢
║ 0A         │ 0B         │ 0C         ║
╟────────────┼────────────┼────────────╢
║ 1A         │ 1B         │ 1C         ║
╟────────────┼────────────┼────────────╢
║ 2A         │ 2B         │ 2C         ║
╚════════════╧════════════╧════════════╝

createStream

table
package exports
createStream
function used to draw a table and append rows.

Parameter: - config: the same as

table
's, except
config.columnDefault.width
and
config.columnCount
must be provided.
import { createStream } from 'table';

const config = { columnDefault: { width: 50 }, columnCount: 1 };

const stream = createStream(config);

setInterval(() => { stream.write([new Date()]); }, 500);

Streaming current date.

table
package uses ANSI escape codes to overwrite the output of the last line when a new row is printed.

The underlying implementation is explained in this Stack Overflow answer.

Streaming supports all of the configuration properties and functionality of a static table (such as auto text wrapping, alignment and padding), e.g.

import { createStream } from 'table';

import _ from 'lodash';

const config = { columnDefault: { width: 50 }, columnCount: 3, columns: [ { width: 10, alignment: 'right' }, { alignment: 'center' }, { width: 10 }

] };

const stream = createStream(config);

let i = 0;

setInterval(() => { let random;

random = _.sample('abcdefghijklmnopqrstuvwxyz', _.random(1, 30)).join('');

stream.write([i++, new Date(), random]); }, 500);

Streaming random data.

getBorderCharacters

Parameter: - template - Type:

'honeywell' | 'norc' | 'ramac' | 'void'
- Required:
true

You can load one of the predefined border templates using

getBorderCharacters
function.
import { table, getBorderCharacters } from 'table';

const data = [ ['0A', '0B', '0C'], ['1A', '1B', '1C'], ['2A', '2B', '2C'] ];

const config = { border: getBorderCharacters(name of the template) };

console.log(table(data, config));

# honeywell

╔════╤════╤════╗ ║ 0A │ 0B │ 0C ║ ╟────┼────┼────╢ ║ 1A │ 1B │ 1C ║ ╟────┼────┼────╢ ║ 2A │ 2B │ 2C ║ ╚════╧════╧════╝

norc

┌────┬────┬────┐ │ 0A │ 0B │ 0C │ ├────┼────┼────┤ │ 1A │ 1B │ 1C │ ├────┼────┼────┤ │ 2A │ 2B │ 2C │ └────┴────┴────┘

ramac (ASCII; for use in terminals that do not support Unicode characters)

+----+----+----+ | 0A | 0B | 0C | |----|----|----| | 1A | 1B | 1C | |----|----|----| | 2A | 2B | 2C | +----+----+----+

void (no borders; see "borderless table" section of the documentation)

0A 0B 0C

1A 1B 1C

2A 2B 2C

Raise an issue if you'd like to contribute a new border template.

Borderless Table

Simply using

void
border character template creates a table with a lot of unnecessary spacing.

To create a more pleasant to the eye table, reset the padding and remove the joining rows, e.g.

const output = table(data, {
    border: getBorderCharacters('void'),
    columnDefault: {
        paddingLeft: 0,
        paddingRight: 1
    },
    drawHorizontalLine: () => false
    }
);

console.log(output);

0A 0B 0C
1A 1B 1C
2A 2B 2C

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.