Table
![js-canonical-style](https://img.shields.io/badge/code%20style-canonical-brightgreen.svg?style=flat)
Produces a string that represents array data in a text table.
![Demo of table displaying a list of missions to the Moon.](https://github.com/gajus/table/raw/HEAD/./.README/demo.png)
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.
Usage
Table data is described using an array (rows) of array (cells).
import table from 'table';
let data,
output;
data = [
['0A', '0B', '0C'],
['1A', '1B', '1C'],
['2A', '2B', '2C']
];
output = table(data);
console.log(output);
โโโโโโคโโโโโคโโโโโ
โ 0A โ 0B โ 0C โ
โโโโโโผโโโโโผโโโโโข
โ 1A โ 1B โ 1C โ
โโโโโโผโโโโโผโโโโโข
โ 2A โ 2B โ 2C โ
โโโโโโงโโโโโงโโโโโ
Cell Content Alignment
{string} config.columns[{number}].alignment
property controls content horizontal alignment within a cell.
Valid values are: "left", "right" and "center".
let config,
data,
output;
data = [
['0A', '0B', '0C'],
['1A', '1B', '1C'],
['2A', '2B', '2C']
];
config = {
columns: {
0: {
alignment: 'left',
minWidth: 10
},
1: {
alignment: 'center',
minWidth: 10
},
2: {
alignment: 'right',
minWidth: 10
}
}
};
output = table(data, config);
console.log(output);
โโโโโโโโโโโโโโคโโโโโโโโโโโโโคโโโโโโโโโโโโโ
โ 0A โ 0B โ 0C โ
โโโโโโโโโโโโโโผโโโโโโโโโโโโโผโโโโโโโโโโโโโข
โ 1A โ 1B โ 1C โ
โโโโโโโโโโโโโโผโโโโโโโโโโโโโผโโโโโโโโโโโโโข
โ 2A โ 2B โ 2C โ
โโโโโโโโโโโโโโงโโโโโโโโโโโโโงโโโโโโโโโโโโโ
Column Width
{number} config.columns[{number}].width
property restricts column width to a fixed width.
let data,
output,
options;
data = [
['0A', '0B', '0C'],
['1A', '1B', '1C'],
['2A', '2B', '2C']
];
options = {
columns: {
1: {
width: 10
}
}
};
output = table(data, options);
console.log(output);
โโโโโโคโโโโโโโโโโโโโคโโโโโ
โ 0A โ 0B โ 0C โ
โโโโโโผโโโโโโโโโโโโโผโโโโโข
โ 1A โ 1B โ 1C โ
โโโโโโผโโโโโโโโโโโโโผโโโโโข
โ 2A โ 2B โ 2C โ
โโโโโโงโโโโโโโโโโโโโงโโโโโ
Custom Border
{object} config.border
property describes characters used to draw the table border.
let config,
data,
output;
data = [
['0A', '0B', '0C'],
['1A', '1B', '1C'],
['2A', '2B', '2C']
];
config = {
border: {
topBody: `โ`,
topJoin: `โฌ`,
topLeft: `โ`,
topRight: `โ`,
bottomBody: `โ`,
bottomJoin: `โด`,
bottomLeft: `โ`,
bottomRight: `โ`,
bodyLeft: `โ`,
bodyRight: `โ`,
bodyJoin: `โ`,
joinBody: `โ`,
joinLeft: `โ`,
joinRight: `โค`,
joinJoin: `โผ`
}
};
output = table(data, config);
console.log(output);
โโโโโโฌโโโโโฌโโโโโ
โ 0A โ 0B โ 0C โ
โโโโโโผโโโโโผโโโโโค
โ 1A โ 1B โ 1C โ
โโโโโโผโโโโโผโโโโโค
โ 2A โ 2B โ 2C โ
โโโโโโดโโโโโดโโโโโ
Draw Horizontal Line
{function} config.drawHorizontalLine
property is a function that is called for every non-content row in the table. The result of the function {boolean}
determines whether a row is drawn.
let data,
output,
options;
data = [
['0A', '0B', '0C'],
['1A', '1B', '1C'],
['2A', '2B', '2C'],
['3A', '3B', '3C'],
['4A', '4B', '4C']
];
options = {
drawHorizontalLine: (index, size) => {
return index === 0 || index === 1 || index === size - 1 || index === size;
}
};
output = table(data, options);
console.log(output);
โโโโโโคโโโโโคโโโโโ
โ 0A โ 0B โ 0C โ
โโโโโโผโโโโโผโโโโโข
โ 1A โ 1B โ 1C โ
โ 2A โ 2B โ 2C โ
โ 3A โ 3B โ 3C โ
โโโโโโผโโโโโผโโโโโข
โ 4A โ 4B โ 4C โ
โโโโโโงโโโโโงโโโโโ
Padding Cell Content
{number} config.columns[{number}].paddingLeft
and {number} config.columns[{number}].paddingRight
properties control content padding within a cell. Property value represents a number of whitespaces used to pad the content.
let config,
data,
output;
data = [
['0A', 'AABBCC', '0C'],
['1A', '1B', '1C'],
['2A', '2B', '2C']
];
config = {
columns: {
0: {
paddingLeft: 3
},
1: {
width: 2,
paddingRight: 3
}
}
};
output = table(data, config);
console.log(output);
โโโโโโโโคโโโโโโโคโโโโโ
โ 0A โ AA โ 0C โ
โ โ BB โ โ
โ โ CC โ โ
โโโโโโโโผโโโโโโโผโโโโโข
โ 1A โ 1B โ 1C โ
โโโโโโโโผโโโโโโโผโโโโโข
โ 2A โ 2B โ 2C โ
โโโโโโโโงโโโโโโโงโโโโโ
Predefined Border Templates
You can load one of the predefined border templates using getBorderCharacters
function.
import table, {
getBorderCharacters
} from 'table';
let config,
data;
data = [
['0A', '0B', '0C'],
['1A', '1B', '1C'],
['2A', '2B', '2C']
];
config = {
border: getBorderCharacters(`name of the template`)
};
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 "bordless 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 plesant to the eye table, reset the padding and remove the joining rows, e.g.
let output;
output = table(data, {
border: getBorderCharacters(`void`),
columnDefault: {
paddingLeft: 0,
paddingRight: 1
},
drawJoin: () => {
return false
}
});
console.log(output);
0A 0B 0C
1A 1B 1C
2A 2B 2C
Streaming
table
package exports createStream
function used to draw a table and append rows.
createStream
requires {number} columnDefault.width
and {number} columnCount
configuration properties.
import {
createStream
} from 'table';
let config,
stream;
config = {
columnDefault: {
width: 50
},
columnCount: 1
};
stream = createStream(config);
setInterval(() => {
stream.write([new Date()]);
}, 500);
![Streaming current date.](https://github.com/gajus/table/raw/HEAD/./.README/streaming.gif)
table
package uses ANSI escape codes to overwrite the output of the last line when a new row is printed. The underlying logic is explained in this Stack Overflow answer.
Text Truncation
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.
{number} config.columns[{number}].truncate
property (default: Infinity
) truncates the text at the specified length.
let config,
data,
output;
data = [
['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
];
config = {
columns: {
0: {
width: 20,
truncate: 100
}
}
};
output = table(data, config);
console.log(output);
โโโโโโโโโโโโโโโโโโโโโโโโ
โ Lorem ipsum dolor si โ
โ t amet, consectetur โ
โ adipiscing elit. Pha โ
โ sellus pulvinar nibh โ
โ sed mauris conva... โ
โโโโโโโโโโโโโโโโโโโโโโโโ
Text Wrapping
table
package implements auto text wrapping, i.e. text that has width greater than the container width will be separated into multiple lines, e.g.
let config,
data,
output;
data = [
['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
];
config = {
columns: {
0: {
width: 20
}
}
};
output = table(data, config);
console.log(output);
โโโโโโโโโโโโโโโโโโโโโโโโ
โ 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. โ
โโโโโโโโโโโโโโโโโโโโโโโโ