1 | # <img src="screenshot.png" width="400" alt="boxen">
|
2 |
|
3 | > Create boxes in the terminal
|
4 |
|
5 | [![Build Status](https://travis-ci.org/sindresorhus/boxen.svg?branch=master)](https://travis-ci.org/sindresorhus/boxen)
|
6 |
|
7 |
|
8 | ## Install
|
9 |
|
10 | ```
|
11 | $ npm install boxen
|
12 | ```
|
13 |
|
14 |
|
15 | ## Usage
|
16 |
|
17 | ```js
|
18 | const boxen = require('boxen');
|
19 |
|
20 | console.log(boxen('unicorn', {padding: 1}));
|
21 | /*
|
22 | ┌─────────────┐
|
23 | │ │
|
24 | │ unicorn │
|
25 | │ │
|
26 | └─────────────┘
|
27 | */
|
28 |
|
29 | console.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 |
|
48 | Type: `string`
|
49 |
|
50 | Text inside the box.
|
51 |
|
52 | #### options
|
53 |
|
54 | ##### borderColor
|
55 |
|
56 | Type: `string`<br>
|
57 | Values: `black` `red` `green` `yellow` `blue` `magenta` `cyan` `white` `gray`
|
58 |
|
59 | Color of the box border.
|
60 |
|
61 | ##### borderStyle
|
62 |
|
63 | Type: `string` `object`<br>
|
64 | Default: `single`<br>
|
65 | Values:
|
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 |
|
103 | Style of the box border.
|
104 |
|
105 | Can 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 |
|
120 | Type: `boolean`<br>
|
121 | Default: `false`
|
122 |
|
123 | Reduce opacity of the border.
|
124 |
|
125 | ##### padding
|
126 |
|
127 | Type: `number` `Object`<br>
|
128 | Default: `0`
|
129 |
|
130 | Space between the text and box border.
|
131 |
|
132 | 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.
|
133 |
|
134 | ##### margin
|
135 |
|
136 | Type: `number` `Object`<br>
|
137 | Default: `0`
|
138 |
|
139 | Space around the box.
|
140 |
|
141 | 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.
|
142 |
|
143 | ##### float
|
144 |
|
145 | Type: `string`<br>
|
146 | Values: `right` `center` `left`<br>
|
147 | Default: `left`
|
148 |
|
149 | Float the box on the available terminal screen space.
|
150 |
|
151 | ##### backgroundColor
|
152 |
|
153 | Type: `string`<br>
|
154 | Values: `black` `red` `green` `yellow` `blue` `magenta` `cyan` `white`
|
155 |
|
156 | Color of the background.
|
157 |
|
158 | ##### align
|
159 |
|
160 | Type: `string`<br>
|
161 | Default: `left`<br>
|
162 | Values: `left` `center` `right`
|
163 |
|
164 | Align 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 |
|
175 | MIT © [Sindre Sorhus](https://sindresorhus.com)
|