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.