@visulima/boxen

Visulima boxen

Create boxes in the terminal, built on top of

cli-boxes, string-width, terminal-size and wrap-ansi

[][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]

---

^{Daniel Bannert's open source work is supported by the community on GitHub Sponsors}

---

Install

npm install @visulima/boxen

yarn add @visulima/boxen

pnpm add @visulima/boxen

Usage

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'

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: '|'
}

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

• 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"