readme.md
1# <img src="screenshot.png" width="400" alt="boxen">
2
3> Create boxes in the terminal
4
5[](https://travis-ci.org/sindresorhus/boxen)
6
7
8## Install
9
10```
11$ npm install boxen
12```
13
14
15## Usage
16
17```js
18const boxen = require('boxen');
19
20console.log(boxen('unicorn', {padding: 1}));
21/*
22┌─────────────┐
23│ │
24│ unicorn │
25│ │
26└─────────────┘
27*/
28
29console.log(boxen('unicorn', {padding: 1, margin: 1, borderStyle: 'double'}));
30/*
31
32 ╔═════════════╗
33 ║ ║
34 ║ unicorn ║
35 ║ ║
36 ╚═════════════╝
37
38*/
39```
40
41
42## API
43
44### boxen(input, [options])
45
46#### input
47
48Type: `string`
49
50Text inside the box.
51
52#### options
53
54##### borderColor
55
56Type: `string`<br>
57Values: `black` `red` `green` `yellow` `blue` `magenta` `cyan` `white` `gray`
58
59Color of the box border.
60
61##### borderStyle
62
63Type: `string` `object`<br>
64Default: `single`<br>
65Values:
66- `single`
67```
68┌───┐
69│foo│
70└───┘
71```
72- `double`
73```
74╔═══╗
75║foo║
76╚═══╝
77```
78- `round` (`single` sides with round corners)
79```
80╭───╮
81│foo│
82╰───╯
83```
84- `single-double` (`single` on top and bottom, `double` on right and left)
85```
86╓───╖
87║foo║
88╙───╜
89```
90- `double-single` (`double` on top and bottom, `single` on right and left)
91```
92╒═══╕
93│foo│
94╘═══╛
95```
96- `classic`
97```
98+---+
99|foo|
100+---+
101```
102
103Style of the box border.
104
105Can be any of the above predefined styles or an object with the following keys:
106
107```js
108{
109 topLeft: '+',
110 topRight: '+',
111 bottomLeft: '+',
112 bottomRight: '+',
113 horizontal: '-',
114 vertical: '|'
115}
116```
117
118##### dimBorder
119
120Type: `boolean`<br>
121Default: `false`
122
123Reduce opacity of the border.
124
125##### padding
126
127Type: `number` `Object`<br>
128Default: `0`
129
130Space between the text and box border.
131
132Accepts 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.
133
134##### margin
135
136Type: `number` `Object`<br>
137Default: `0`
138
139Space around the box.
140
141Accepts 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.
142
143##### float
144
145Type: `string`<br>
146Values: `right` `center` `left`<br>
147Default: `left`
148
149Float the box on the available terminal screen space.
150
151##### backgroundColor
152
153Type: `string`<br>
154Values: `black` `red` `green` `yellow` `blue` `magenta` `cyan` `white`
155
156Color of the background.
157
158##### align
159
160Type: `string`<br>
161Default: `left`<br>
162Values: `left` `center` `right`
163
164Align the text in the box based on the widest line.
165
166
167## Related
168
169- [boxen-cli](https://github.com/sindresorhus/boxen-cli) - CLI for this module
170- [cli-boxes](https://github.com/sindresorhus/cli-boxes) - Boxes for use in the terminal
171
172
173## License
174
175MIT © [Sindre Sorhus](https://sindresorhus.com)
176
){kind=link}