visulimaVisulima boxen
Create boxes in the terminal, built on top of cli-boxes, string-width, terminal-size and wrap-ansi
Daniel Bannert's open source work is supported by the community on GitHub Sponsors
Install
npm install @visulima/boxenyarn add @visulima/boxenpnpm add @visulima/boxenUsage
import { 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.
API
boxen(text, options?)
text
Type: string
Text inside the box.
options
Type: object
borderColor
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);
}
},
}),
);borderStyle
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'
fooStyle 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: '|'
}headerText
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 │
└─────────┘
*/headerColor
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),
}),
);headerAlignment
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│
└───────────────┘footerText
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 ┘
*/footerColor
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),
}),
);footerAlignment
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 ┘width
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 │
// └─────────────┘height
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│
// │ │
// │ │
// └───────┘fullscreen
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],
}),
);padding
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.
margin
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.
float
Type: string\
Default: 'left'\
Values: 'right' 'center' 'left'
Float the box on the available terminal screen space.
textColor
Type: (text: string) => string\
import { bgRed } from "@visulima/colorize";
import { boxen } from "@visulima/boxen";
console.log(
boxen("foo bar", {
textColor: (text) => bgRed(text),
}),
);textAlignment
Type: string\
Default: 'left'\
Values: 'left' 'center' 'right'
Align the text in the box based on the widest line.
transformTabToSpace
Type: false | number\
Default: '4'
Transform tab characters to spaces. Set to false to disable.
Supported Node.js Versions
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.
Contributing
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.
Credits
License
The visulima boxen is open-sourced software licensed under the MIT