Create boxes in the terminal, built on top of
Daniel Bannert's open source work is supported by the community on GitHub Sponsors
npm install @visulima/boxenyarn add @visulima/boxenpnpm add @visulima/boxenimport { boxen } from "@visulima/boxen";
console.log(boxen("unicorn", { padding: 1 }));
/*
┌─────────────┐
│ │
│ unicorn │
│ │
└─────────────┘
*/
console.log(boxen("unicorn", { padding: 1, margin: 1, borderStyle: "double" }));
/*
╔═════════════╗
║ ║
║ unicorn ║
║ ║
╚═════════════╝
*/
console.log(
boxen("unicorns love rainbows", {
headerText: "magical",
headerAlignment: "center",
}),
);
/*
┌────── magical ───────┐
│unicorns love rainbows│
└──────────────────────┘
*/
console.log(
boxen("unicorns love rainbows", {
headerText: "magical",
headerAlignment: "center",
footerText: "magical",
footerAlignment: "center",
}),
);
/*
┌────── magical ───────┐
│unicorns love rainbows│
└────── magical ───────┘
*/Check more examples in the examples/boxen folder.
Type: string
Text inside the box.
Type: object
Type: (border: string, position: BorderPosition, length: number) => string\
Color of the box border.
import { boxen } from "@visulima/boxen";
import { red, green, yellow, blue } from "@visulima/colorize";
console.log(
boxen("Hello, world!", {
borderColor: (border, position) => {
if (["top", "topLeft", "topRight"].includes(position)) {
return red(border);
}
if (position === "left") {
return yellow(border);
}
if (position === "right") {
return green(border);
}
if (["bottom", "bottomLeft", "bottomRight"].includes(position)) {
return blue(border);
}
},
}),
);Type: string | object
Default: 'single'
Values:
'single'
┌───┐
│foo│
└───┘
'double'
╔═══╗
║foo║
╚═══╝
-
'round'('single'sides with round corners)
╭───╮
│foo│
╰───╯
'bold'
┏━━━┓
┃foo┃
┗━━━┛
-
'singleDouble'('single'on top and bottom,'double'on right and left)
╓───╖
║foo║
╙───╜
-
'doubleSingle'('double'on top and bottom,'single'on right and left)
╒═══╕
│foo│
╘═══╛
'classic'
+---+
|foo|
+---+
'arrow'
↘↓↓↓↙
→foo←
↗↑↑↑↖
'none'
foo
Style of the box border.
Can be any of the above predefined styles or an object with the following keys:
{
topLeft: '+',
topRight: '+',
bottomLeft: '+',
bottomRight: '+',
top: '-',
bottom: '-',
left: '|',
right: '|'
}Type: string
Display a title at the top of the box. If needed, the box will horizontally expand to fit the text.
Example:
import { boxen } from "@visulima/boxen";
console.log(boxen("foo bar", { headerText: "example" }));
/*
┌ example ┐
│foo bar │
└─────────┘
*/Type: (text: string) => string
import { red } from "@visulima/colorize";
import { boxen } from "@visulima/boxen";
console.log(
boxen("foo bar", {
headerText: "example",
headerColor: (text) => red(text),
}),
);Type: string
Default: 'left'
Align the text in the top bar.
Values:
'left'
┌ example ──────┐
│foo bar foo bar│
└───────────────┘
'center'
┌─── example ───┐
│foo bar foo bar│
└───────────────┘
'right'
┌────── example ┐
│foo bar foo bar│
└───────────────┘
Type: string
Display a text at the bottom of the box. If needed, the box will horizontally expand to fit the text.
Example:
import { boxen } from "@visulima/boxen";
console.log(boxen("foo bar", { footerText: "example" }));
/*
┌─────────┐
│foo bar │
└ example ┘
*/Type: (text: string) => string
import { red } from "@visulima/colorize";
import { boxen } from "@visulima/boxen";
console.log(
boxen("foo bar", {
footerText: "example",
footerColor: (text) => red(text),
}),
);Type: string
Default: 'left'
Align the footer text.
Values:
'left'
┌───────────────┐
│foo bar foo bar│
└ Footer Text ──┘
'center'
┌───────────────┐
│foo bar foo bar│
└─── example ───┘
'right'
┌───────────────┐
│foo bar foo bar│
└────── example ┘
Type: number
Set a fixed width for the box.
Note: This disables terminal overflow handling and may cause the box to look broken if the user's terminal is not wide enough.
import { boxen } from "@visulima/boxen";
console.log(boxen("foo bar", { width: 15 }));
// ┌─────────────┐
// │foo bar │
// └─────────────┘Type: number
Set a fixed height for the box.
Note: This option will crop overflowing content.
import { boxen } from "@visulima/boxen";
console.log(boxen("foo bar", { height: 5 }));
// ┌───────┐
// │foo bar│
// │ │
// │ │
// └───────┘Type: boolean | (width: number, height: number) => [width: number, height: number]
Whether or not to fit all available space within the terminal.
Pass a callback function to control box dimensions:
import { boxen } from "@visulima/boxen";
console.log(
boxen("foo bar", {
fullscreen: (width, height) => [width, height - 1],
}),
);Type: number | object
Default: 0
Space between the text and box border.
Accepts a number or an object with any of the top, right, bottom, left properties. When a number is specified, the left/right padding is 3 times the top/bottom to make it look nice.
Type: number | object
Default: 0
Space around the box.
Accepts a number or an object with any of the top, right, bottom, left properties. When a number is specified, the left/right margin is 3 times the top/bottom to make it look nice.
Type: string
Default: 'left'
Values: 'right' 'center' 'left'
Float the box on the available terminal screen space.
Type: (text: string) => string\
import { bgRed } from "@visulima/colorize";
import { boxen } from "@visulima/boxen";
console.log(
boxen("foo bar", {
textColor: (text) => bgRed(text),
}),
);Type: string
Default: 'left'
Values: 'left' 'center' 'right'
Align the text in the box based on the widest line.
Type: false | number
Default: '4'
Transform tab characters to spaces. Set to false to disable.
26.3 15:00 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 boxen is open-sourced software licensed under the MIT