sindresorhus/boxen

Create boxes in the terminal

boxen

Create boxes in the terminal

Install

npm install boxen

Usage

import boxen from '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', {title: 'magical', titleAlignment: 'center'}));
/*
┌────── magical ───────┐
│unicorns love rainbows│
└──────────────────────┘
*/

API

boxen(text, options?)

text

Type: string

Text inside the box.

options

Type: object

borderColor

Type: string
Values: 'black' 'red' 'green' 'yellow' 'blue' 'magenta' 'cyan' 'white' 'gray' or a hex value like '#ff0000'

Color of the box 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: '|'
}

dimBorder

Type: boolean
Default: false

Reduce opacity of the border.

title

Type: string

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

Example:

console.log(boxen('foo bar', {title: 'example'}));
/*
┌ example ┐
│foo bar  │
└─────────┘
*/

titleAlignment

Type: string
Default: 'left'

Align the title in the top bar.

Values:

• 'left'

/*
┌ example ──────┐
│foo bar foo bar│
└───────────────┘
*/

• 'center'

/*
┌─── example ───┐
│foo bar foo bar│
└───────────────┘
*/

• 'right'

/*
┌────── example ┐
│foo bar foo bar│
└───────────────┘
*/

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 '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 '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 '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.

backgroundColor

Type: string
Values: 'black' 'red' 'green' 'yellow' 'blue' 'magenta' 'cyan' 'white' 'gray' or a hex value like '#ff0000'

Color of the background.

textAlignment

Type: string
Default: 'left'
Values: 'left' 'center' 'right'

Align the text in the box based on the widest line.

Maintainer

• Sindre Sorhus
• Caesarovich

Related

• boxen-cli - CLI for this module
• cli-boxes - Boxes for use in the terminal

boxen's Issues

Fullscreen option

What about add fullscreen option for create a fullscreen box?

Newlines get stripped out

When the width of the box (including margin) exceeds the number of available columns (which defaults to 80 if it cannot be detected), the box is rendered without any newlines. This causes lots hard-to-read output from clients which don't set a width (such as serverless-offline) seemingly(?) no reason.

┌──────────────────────────────────────────────────────────────────────────────┐│                                                                              ││   GET | http://localhost:3000/dev/namespace-export-1                         ││   POST |                                                                     ││   http://localhost:3000/2015-03-31/functions/namespaceExport1/invocations    ││   GET | http://localhost:3000/dev/namespace-export-2                         ││   POST |                                                                     ││   http://localhost:3000/2015-03-31/functions/namespaceExport2/invocations    ││   GET | http://localhost:3000/dev/namespace-export-3                         ││   POST |                                                                     ││   http://localhost:3000/2015-03-31/functions/namespaceExport3/invocations    ││   GET | http://localhost:3000/dev/namespace-export-4                         ││   POST |                                                                     ││   http://localhost:3000/2015-03-31/functions/namespaceExport4/invocations    ││   GET | http://localhost:3000/dev/js-extension                               ││   POST |                                                                     ││   http://localhost:3000/2015-03-31/functions/js-extension/invocations        ││   GET | http://localhost:3000/dev/cjs-extension                              ││   POST |                                                                     ││   http://localhost:3000/2015-03-31/functions/cjs-extension/invocations       ││   GET | http://localhost:3000/dev/package-type                               ││   POST |                                                                     ││   http://localhost:3000/2015-03-31/functions/package-type/invocations        ││                                                                              │└──────────────────────────────────────────────────────────────────────────────┘

This occurs extra often as the margin-shrinking logic will at most shrink options.width to columns - BORDERS_WIDTH, in which case this conditional is still guaranteed to be true, causing newlines to be removed.

Maybe I'm misunderstanding but is there any particular reason for stripping out newlines if the box would be too wide? I feel like the result is less readable than if it were just left up to the terminal to wrap or truncate lines.

Upgrade `boxen-cli`

With recent changes.

https://github.com/sindresorhus/boxen-cli

Can you do multi-line text?

Can you do multi-line text?

Update widest-line vulnerability?

Hi,

Any chance you could update widest-line to the latest version when it's published? sindresorhus/widest-line#11

Chasing this dependency down a tree and you're next up the tree.

Thanks.

boxen causes two versions of string-width to be installed.

This is caused by the use of string-width 2.x with widest-line 1.x. Now that widest-line 2.0.0 is released this module can use it.

Typescript types

Any plans for TS support?

Support more colors

Chalk now supports 16 million colors, we should support that in the borderColor and backgroundColor options by also accept a HEX color.

https://github.com/chalk/chalk#256-and-truecolor-color-support

Extend backgroundColor to under the border

Hi, when I specify the backgroundColor, it is applied only immediately just under the thext inside the box. But then there is a black moat between the text and the border, like this:

To achieve something like this:

This is under Windows cmd terminal, so maybe the background gets rendered better in other terminals. Also, I suspect putting bacground to fill inside of the box might not be possible as adding background color to border glyphs would spill that colour to outside the box as well?

Lastly, I know this is not core functionality of boxen, but consider adding a simple option to change text color. Can be achieved with Chalk etc, but for anyone needing a one dependency solution this might be enough..

const boxen = require("boxen");
const color = require("chalk");
console.log(
  boxen(color.hex("#07171d")("this is some text"), {
    margin: { top: 1, right: 0, bottom: 1, left: 2 },
    padding: { top: 0, right: 2, bottom: 0, left: 2 },
    borderColor: "#e29578",
    backgroundColor: "#e0f0f5",
    borderStyle: "double",
  })
);

New option width

Would be nice if I could say that the box should be 90 characters wide.

Boxen crashes on padding when terminal size < box size

When the box size exceeds the terminal size, padWidth turns into a negative value, which causes the repeat function to error:

const padWidth = (columns - contentWidth) / 2;
marginLeft = PAD.repeat(padWidth);

We see this failure when using center alignment (our default) but not when right is used.

Feature Request: Global setting

Is there an easy way to set boxen's style object once and no longer need to pass the style object every time I use boxen()?

Margin option

It might be useful with a margin option. I don't personally need it, but would welcome a pull request.

Boxen colors don't get saved to console logs

I suspect this stems from how boxen core functionality and actually in some cases is preferred way of working. Just wanted to report/point out that boxen borderColor and backgroundColor values don't get saved to console text log files when using pm2process manager. However Chalk does put those colour strings with text, so that when the logs are later reviewed with pm2 --logs, the colours are displayed. What worries me, if I wrap a chalk-coloured string inside boxen, the chalk colours get stripped out as well. The first box has text colour changed to blue through Chalk library. Notice at the bottom of screenshot that two Chalk strings not wrapped in boxen get displayed with colours.

console.log displayed back in terminal:

From original:

Could you add a settings toggle to let users decide whether boxen strips colours from output strings or not? Unless I'm misunderstanding and this is an issue with how pm2 saves process console logs to file.

const boxen = require("boxen");
const color = require("chalk");

console.log(
  boxen(color.hex("#007ea8")("Results Monitor server is running"), {
    margin: {top:1, right:0, bottom:1, left:2},
    padding: {top:0, right:2, bottom:0, left:2},
    // dimBorder: false,
    borderColor: "#023255",
    backgroundColor: "#010c14",
    borderStyle: "double", 
  })
);
console.log(
  boxen(color.hex("#07171d")("this is some text"), {
    margin: { top: 1, right: 0, bottom: 1, left: 2 },
    padding: { top: 0, right: 2, bottom: 0, left: 2 },
    borderColor: "#e29578",
    backgroundColor: "#e0f0f5",
    borderStyle: "double",
  })
);
console.log(color.bgHex("#e8edde").hex("#000214")("qPCR Monitor is running"));
console.log(color.bgHex("#d0dcd6").hex("#000214")(`Observing folder: ${entry}`));

Problem with BorderStyle

import * as boxen from 'boxen';

console.log(boxen("text", { padding: 1, margin: 1, borderStyle: 'double'}));

returns

....Type '"double"' is not assignable to type 'BorderStyle | CustomBorderStyle'.

Table border wrongly formatted

When printing items with colors, the border gets wrongly rendered:

Is there any workaround for this?

PS: I'm using Chalk for the text coloring.

Multiple boxes on same line (feature request)

Personally I really, really like this package :)

It would, however, be really cool if the package had the possibility of printing multiple boxes on the same line. Could be cool to use for simple terminal games (like tic tac toe) or something like that :)

Here's a (really) quick example of how I that might look:

Hope this ("feature request") makes sense :) Just a thought at least.

Br, Jonas

ES module not supported

when i try to use boxen i have getting this error, before i update my node version this worked for me

require() of ES Module E:\Projects\Skysoft\Framework\api\node_modules\boxen\index.js from E:\Projects\Skysoft\Framework\api\helpers\console.helper.ts not supported.
Instead change the require of index.js in E:\Projects\Skysoft\Framework\api\helpers\console.helper.ts to a dynamic import() which is available in all CommonJS modules

i tried those methods nothing work

import boxen from 'boxen'
import * as boxen from 'boxen'
import {boxen} from 'boxen'
const boxen = require('boxen')

how can i fix this without downgrade node

node - v16.18.0
npm - v8.19.2

cropping leading whitespace in new version ??

i have an npx business card that's built on boxen. When i use [email protected] it displays leading whitespace in the strings, for example:

npx [email protected]

However, if i build with the latest version ([email protected]), it displays without any leading whitespace:

npx [email protected]

Has anyone else notice this problem ??

Do you mind if I do some code refactoring?

I think this library could benefit from code refactoring.

I wouldn't open a PR for anything that makes breaking changes. Just clearer code.

Border style type issue

Version:
^4.2.0

Issue:
The borderStyle option throws type error in TypeScript ^4.1.2. None of these seem to work: single, double, round, bold, singleDouble, doubleSingle, classic.

Screenshot:

Support text wrapping

Hello, I get a box collapse when I want to print a string longer than the window width. Is it a normal behavior?

Screenshot:

Steps to reproduce:

const boxen = require('boxen');
console.log(boxen('unicornddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd', {padding: 1}));

Box background color option

Just use chalk to set the background on all the content. PR welcome :)

New option: title

Hi, would be ncie to have the possibility to add a title to a box. Like:

┌Tasks─────────────┐                                                                                                                                                                                                                                                                                       │Task number 1...                             │
└───────────────  ┘

I've already edited the source code to make it possible, I can open a PR.

import problem with 7.1.1

After updating to boxen 7.1.1 we see the following error when executing our app.

/.../node_modules/ts-node/dist/index.js:851
            return old(m, filename);
                   ^
Error [ERR_REQUIRE_ESM]: require() of ES Module /.../node_modules/boxen/index.js from /.../app.ts not supported.
Instead change the require of index.js in /.../app.ts to a dynamic import() which is available in all CommonJS modules.

Our code imports boxen like this:

import boxen from 'boxen';

We use ts-node to run the app.

Strange behaviour when combining chalk and wrap-ansi as input

The way that boxen splits up the input text by newlines makes it so that ANSI style codes end up
potentially split between the different strings, producing an unexpected result.

In both of these examples:

console.log(boxen(wrapAnsi(chalk.blue('Unicorns are awesome'), 10), {borderColor: 'green'}))
console.log(boxen(wrapAnsi(chalk.blue('Unicorns are awesome'), 10)))

The lines variable, which holds the result of splitting the string into lines, has the following content:

[ '\u001b[94mUnicorns', 'are', 'awesome\u001b[39m' ]

The workaround would be to switch the order in which these tools are applied.

These two examples:

console.log(boxen(chalk.blue(wrapAnsi('Unicorns are awesome', 10)), {borderColor: 'green'}))
console.log(boxen(chalk.blue(wrapAnsi('Unicorns are awesome', 10))))

Exhibit the expected behaviour.

Mark Spacing properties optional

boxen/index.js

Lines 37 to 43 in af821c6

	} : {
	top: 0,
	right: 0,
	bottom: 0,
	left: 0,
	...detail,
	};

margin and padding options are being spread over default values, so the Spacing type could allow these properties to be optional.

Max width option

It would be nice to have a max width option as an alternative to a set width.

How would you go about centering a box?

I'm not sure it is even possible but It would be nice to have a property to center the box on screen.

Allow border to be optional.

This tool has a lot of great features for creating boxes, and some of those features would be nice on their own. For instance, fullscreen would be great in some cases even without a border.

My use case, however, incorporates boxen into another utility. In order to achieve "no border", I have given boxen a "ghost border" which I strip after boxen's done working.

borderStyle: {
	topLeft: ' ',
	topRight: ' ',
	bottomLeft: ' ',
	bottomRight: ' ',
	top: ' ',
	bottom: ' ',
	left: ' ',
	right: ' '
}

Upgrade `cli-boxes` dependency

https://github.com/sindresorhus/cli-boxes/releases/tag/v3.0.0

require() of ES Module not supported. With Typescript 4.6 and boxen 6.0.0 or higher.

Downgrading the package version to 5.1.2 fix it.

replit example

COMPLETE LOG
require() of ES Module project\node_modules\boxen\index.js from project\file.ts not supported. Instead change the require of index.js in project\file.ts to a dynamic import() which is available in all CommonJS modules.

Problem with emoji sizes

Boxen is amazing but has troubles with emojis.

I tried to devise a PR myself, but apparently it's in a sub-sub dependency, so you'll be faster than me at fixing it:

I enclosed the strings with " to ensure it was not from my side.
Here is the text for reproducing:

🙂  CHARACTERISTICS 💗
"👶🏽  level.........1"
"💗  health........1"
"💙  mana..........0"
"🏋🏽  strength......1"
"🤸🏽  agility.......1"
"🏊🏽  vitality......1"
"👵🏽  wisdom........1"
"🤹🏼‍♀️  luck..........1"

Text wrapping doesn't account for margin

From what I can see there is no way currently to make this work:

The problem is that our CLI includes a prefix for each line and boxen doesn't know that. I've wanted to include the margin in the options so I would just move the box to the right by the appropriate amount of characters (known to me). However, this doesn't work - since text wrapping etc happens before margin is even looked at.

boxen is not working