boxen

Create boxes in the terminal

![](screenshot.png)

Install

$ npm install boxen

Usage

const boxen = require('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| +---+

Style of the box border.

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

{
	topLeft: '+',
	topRight: '+',
	bottomLeft: '+',
	bottomRight: '+',
	horizontal: '-',
	vertical: '|'
}

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:
js console.log(boxen('foo bar', {title: 'example'})); /* ┌ example ┐ │foo bar │ └─────────┘ */

titleAlignment

Type: string\
Default: 'left'

Align the title in the top bar.

Values:
- 'left'
js /* ┌ example ──────┐ │foo bar foo bar│ └───────────────┘ */
- 'center'
js /* ┌─── example ───┐ │foo bar foo bar│ └───────────────┘ */
- 'right'
js /* ┌────── example ┐ │foo bar foo bar│ └───────────────┘ */

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