---

---

Install

1npm install @visulima/boxen

1yarn add @visulima/boxen

1pnpm add @visulima/boxen

Usage

1import { boxen } from "@visulima/boxen";
2
3console.log(boxen("unicorn", { padding: 1 }));
4/*
5┌─────────────┐
6│             │
7│   unicorn   │
8│             │
9└─────────────┘
10*/
11
12console.log(boxen("unicorn", { padding: 1, margin: 1, borderStyle: "double" }));
13/*
14   ╔═════════════╗
15   ║             ║
16   ║   unicorn   ║
17   ║             ║
18   ╚═════════════╝
19
20*/
21
22console.log(
23    boxen("unicorns love rainbows", {
24        headerText: "magical",
25        headerAlignment: "center",
26    }),
27);
28/*
29┌────── magical ───────┐
30│unicorns love rainbows│
31└──────────────────────┘
32*/
33
34console.log(
35    boxen("unicorns love rainbows", {
36        headerText: "magical",
37        headerAlignment: "center",
38        footerText: "magical",
39        footerAlignment: "center",
40    }),
41);
42/*
43┌────── magical ───────┐
44│unicorns love rainbows│
45└────── magical ───────┘
46*/

Check more examples in the examples folder.

API

boxen(text, options?)

text

Type: string

Text inside the box.

options

Type: object

borderColor

Type: (border: string, position: BorderPosition, length: number) => string\

Set the color of the box border.

1import { boxen } from "@visulima/boxen";
2import { red, green, yellow, blue } from "@visulima/colorize";
3
4console.log(
5    boxen("Hello, world!", {
6        borderColor: (border, position) => {
7            if (["top", "topLeft", "topRight"].includes(position)) {
8                return red(border);
9            }
10
11            if (position === "left") {
12                return yellow(border);
13            }
14
15            if (position === "right") {
16                return green(border);
17            }
18
19            if (["bottom", "bottomLeft", "bottomRight"].includes(position)) {
20                return blue(border);
21            }
22        },
23    }),
24);

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'

foo

Style of the box border.

Can be any of the above predefined styles or an object with the following keys:

1{
2    topLeft: '+',
3    topRight: '+',
4    bottomLeft: '+',
5    bottomRight: '+',
6    top: '-',
7    bottom: '-',
8    left: '|',
9    right: '|'
10}

headerText

Type: string

Display text at the top of the box. If needed, the box will horizontally expand to fit the text.

Example:

1import { boxen } from "@visulima/boxen";
2
3console.log(boxen("foo bar", { headerText: "example" }));
4
5/*
6┌ example ┐
7│foo bar  │
8└─────────┘
9*/

headerColor

Type: (text: string) => string

1import { red } from "@visulima/colorize";
2import { boxen } from "@visulima/boxen";
3
4console.log(
5    boxen("foo bar", {
6        headerText: "example",
7        headerColor: (text) => red(text),
8    }),
9);

headerAlignment

Type: string
Default: 'left'

Align the text in the top bar.

Values:

• 'left'

1┌ example ──────┐
2│foo bar foo bar│
3└───────────────┘

• 'center'

1┌─── example ───┐
2│foo bar foo bar│
3└───────────────┘

• 'right'

1┌────── example ┐
2│foo bar foo bar│
3└───────────────┘

footerText

Type: string

Display text at the bottom of the box. If needed, the box will horizontally expand to fit the text.

Example:

1import { boxen } from "@visulima/boxen";
2
3console.log(boxen("foo bar", { footerText: "example" }));
4
5/*
6┌─────────┐
7│foo bar  │
8└ example ┘
9*/

footerColor

Type: (text: string) => string

1import { red } from "@visulima/colorize";
2import { boxen } from "@visulima/boxen";
3
4console.log(
5    boxen("foo bar", {
6        footerText: "example",
7        footerColor: (text) => red(text),
8    }),
9);

footerAlignment

Type: string
Default: 'left'

Align the footer text.

Values:

• 'left'

1┌───────────────┐
2│foo bar foo bar│
3└ Footer Text ──┘

• 'center'

1┌───────────────┐
2│foo bar foo bar│
3└─── example ───┘

• 'right'

1┌───────────────┐
2│foo bar foo bar│
3└────── 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.

1import { boxen } from "@visulima/boxen";
2
3console.log(boxen("foo bar", { width: 15 }));
4// ┌─────────────┐
5// │foo bar      │
6// └─────────────┘

height

Type: number

Set a fixed height for the box.

Note: This option will crop overflowing content.

1import { boxen } from "@visulima/boxen";
2
3console.log(boxen("foo bar", { height: 5 }));
4// ┌───────┐
5// │foo bar│
6// │       │
7// │       │
8// └───────┘

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:

1import { boxen } from "@visulima/boxen";
2
3console.log(
4    boxen("foo bar", {
5        fullscreen: (width, height) => [width, height - 1],
6    }),
7);

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\

1import { bgRed } from "@visulima/colorize";
2import { boxen } from "@visulima/boxen";
3
4console.log(
5    boxen("foo bar", {
6        textColor: (text) => bgRed(text),
7    }),
8);

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

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

• boxen
• ansi-align
• Daniel Bannert
• All Contributors

License

The visulima boxen is open-sourced software licensed under the [MIT][license-url]

[typescript-url]: https://www.typescriptlang.org/ "TypeScript" "typescript" [license-image]: https://img.shields.io/npm/l/@visulima/boxen?color=blueviolet&style=for-the-badge [license-url]: LICENSE.md "license" [npm-image]: https://img.shields.io/npm/v/@visulima/boxen/latest.svg?style=for-the-badge&logo=npm [npm-url]: https://www.npmjs.com/package/@visulima/boxen/v/latest "npm"