1 | # boxen
|
2 |
|
3 | > Create boxes in the terminal
|
4 |
|
5 | ![](screenshot.png)
|
6 |
|
7 | ## Install
|
8 |
|
9 | ```sh
|
10 | npm install boxen
|
11 | ```
|
12 |
|
13 | ## Usage
|
14 |
|
15 | ```js
|
16 | import boxen from 'boxen';
|
17 |
|
18 | console.log(boxen('unicorn', {padding: 1}));
|
19 | /*
|
20 | ┌─────────────┐
|
21 | │ │
|
22 | │ unicorn │
|
23 | │ │
|
24 | └─────────────┘
|
25 | */
|
26 |
|
27 | console.log(boxen('unicorn', {padding: 1, margin: 1, borderStyle: 'double'}));
|
28 | /*
|
29 |
|
30 | ╔═════════════╗
|
31 | ║ ║
|
32 | ║ unicorn ║
|
33 | ║ ║
|
34 | ╚═════════════╝
|
35 |
|
36 | */
|
37 |
|
38 | console.log(boxen('unicorns love rainbows', {title: 'magical', titleAlignment: 'center'}));
|
39 | /*
|
40 | ┌────── magical ───────┐
|
41 | │unicorns love rainbows│
|
42 | └──────────────────────┘
|
43 | */
|
44 | ```
|
45 |
|
46 | ## API
|
47 |
|
48 | ### boxen(text, options?)
|
49 |
|
50 | #### text
|
51 |
|
52 | Type: `string`
|
53 |
|
54 | Text inside the box.
|
55 |
|
56 | #### options
|
57 |
|
58 | Type: `object`
|
59 |
|
60 | ##### borderColor
|
61 |
|
62 | Type: `string`\
|
63 | Values: `'black'` `'red'` `'green'` `'yellow'` `'blue'` `'magenta'` `'cyan'` `'white'` `'gray'` or a hex value like `'#ff0000'`
|
64 |
|
65 | Color of the box border.
|
66 |
|
67 | ##### borderStyle
|
68 |
|
69 | Type: `string | object`\
|
70 | Default: `'single'`\
|
71 | Values:
|
72 | - `'single'`
|
73 | ```
|
74 | ┌───┐
|
75 | │foo│
|
76 | └───┘
|
77 | ```
|
78 | - `'double'`
|
79 | ```
|
80 | ╔═══╗
|
81 | ║foo║
|
82 | ╚═══╝
|
83 | ```
|
84 | - `'round'` (`'single'` sides with round corners)
|
85 | ```
|
86 | ╭───╮
|
87 | │foo│
|
88 | ╰───╯
|
89 | ```
|
90 | - `'bold'`
|
91 | ```
|
92 | ┏━━━┓
|
93 | ┃foo┃
|
94 | ┗━━━┛
|
95 | ```
|
96 | - `'singleDouble'` (`'single'` on top and bottom, `'double'` on right and left)
|
97 | ```
|
98 | ╓───╖
|
99 | ║foo║
|
100 | ╙───╜
|
101 | ```
|
102 | - `'doubleSingle'` (`'double'` on top and bottom, `'single'` on right and left)
|
103 | ```
|
104 | ╒═══╕
|
105 | │foo│
|
106 | ╘═══╛
|
107 | ```
|
108 | - `'classic'`
|
109 | ```
|
110 | +---+
|
111 | |foo|
|
112 | +---+
|
113 | ```
|
114 | - `'arrow'`
|
115 | ```
|
116 | ↘↓↓↓↙
|
117 | →foo←
|
118 | ↗↑↑↑↖
|
119 | ```
|
120 | - `'none'`
|
121 | ```
|
122 | foo
|
123 | ```
|
124 |
|
125 | Style of the box border.
|
126 |
|
127 | Can be any of the above predefined styles or an object with the following keys:
|
128 |
|
129 | ```js
|
130 | {
|
131 | topLeft: '+',
|
132 | topRight: '+',
|
133 | bottomLeft: '+',
|
134 | bottomRight: '+',
|
135 | top: '-',
|
136 | bottom: '-',
|
137 | left: '|',
|
138 | right: '|'
|
139 | }
|
140 | ```
|
141 |
|
142 | ##### dimBorder
|
143 |
|
144 | Type: `boolean`\
|
145 | Default: `false`
|
146 |
|
147 | Reduce opacity of the border.
|
148 |
|
149 | ##### title
|
150 |
|
151 | Type: `string`
|
152 |
|
153 | Display a title at the top of the box.
|
154 | If needed, the box will horizontally expand to fit the title.
|
155 |
|
156 | Example:
|
157 | ```js
|
158 | console.log(boxen('foo bar', {title: 'example'}));
|
159 | /*
|
160 | ┌ example ┐
|
161 | │foo bar │
|
162 | └─────────┘
|
163 | */
|
164 | ```
|
165 |
|
166 | ##### titleAlignment
|
167 |
|
168 | Type: `string`\
|
169 | Default: `'left'`
|
170 |
|
171 | Align the title in the top bar.
|
172 |
|
173 | Values:
|
174 | - `'left'`
|
175 | ```js
|
176 | /*
|
177 | ┌ example ──────┐
|
178 | │foo bar foo bar│
|
179 | └───────────────┘
|
180 | */
|
181 | ```
|
182 | - `'center'`
|
183 | ```js
|
184 | /*
|
185 | ┌─── example ───┐
|
186 | │foo bar foo bar│
|
187 | └───────────────┘
|
188 | */
|
189 | ```
|
190 | - `'right'`
|
191 | ```js
|
192 | /*
|
193 | ┌────── example ┐
|
194 | │foo bar foo bar│
|
195 | └───────────────┘
|
196 | */
|
197 | ```
|
198 |
|
199 | ##### width
|
200 |
|
201 | Type: `number`
|
202 |
|
203 | Set a fixed width for the box.
|
204 |
|
205 | *Note:* This disables terminal overflow handling and may cause the box to look broken if the user's terminal is not wide enough.
|
206 |
|
207 | ```js
|
208 | import boxen from 'boxen';
|
209 |
|
210 | console.log(boxen('foo bar', {width: 15}));
|
211 | // ┌─────────────┐
|
212 | // │foo bar │
|
213 | // └─────────────┘
|
214 | ```
|
215 |
|
216 | ##### height
|
217 |
|
218 | Type: `number`
|
219 |
|
220 | Set a fixed height for the box.
|
221 |
|
222 | *Note:* This option will crop overflowing content.
|
223 |
|
224 | ```js
|
225 | import boxen from 'boxen';
|
226 |
|
227 | console.log(boxen('foo bar', {height: 5}));
|
228 | // ┌───────┐
|
229 | // │foo bar│
|
230 | // │ │
|
231 | // │ │
|
232 | // └───────┘
|
233 | ```
|
234 |
|
235 | ##### fullscreen
|
236 |
|
237 | Type: `boolean | (width: number, height: number) => [width: number, height: number]`
|
238 |
|
239 | Whether or not to fit all available space within the terminal.
|
240 |
|
241 | Pass a callback function to control box dimensions:
|
242 |
|
243 | ```js
|
244 | import boxen from 'boxen';
|
245 |
|
246 | console.log(boxen('foo bar', {
|
247 | fullscreen: (width, height) => [width, height - 1],
|
248 | }));
|
249 | ```
|
250 |
|
251 | ##### padding
|
252 |
|
253 | Type: `number | object`\
|
254 | Default: `0`
|
255 |
|
256 | Space between the text and box border.
|
257 |
|
258 | 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.
|
259 |
|
260 | ##### margin
|
261 |
|
262 | Type: `number | object`\
|
263 | Default: `0`
|
264 |
|
265 | Space around the box.
|
266 |
|
267 | 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.
|
268 |
|
269 | ##### float
|
270 |
|
271 | Type: `string`\
|
272 | Default: `'left'`\
|
273 | Values: `'right'` `'center'` `'left'`
|
274 |
|
275 | Float the box on the available terminal screen space.
|
276 |
|
277 | ##### backgroundColor
|
278 |
|
279 | Type: `string`\
|
280 | Values: `'black'` `'red'` `'green'` `'yellow'` `'blue'` `'magenta'` `'cyan'` `'white'` `'gray'` or a hex value like `'#ff0000'`
|
281 |
|
282 | Color of the background.
|
283 |
|
284 | ##### textAlignment
|
285 |
|
286 | Type: `string`\
|
287 | Default: `'left'`\
|
288 | Values: `'left'` `'center'` `'right'`
|
289 |
|
290 | Align the text in the box based on the widest line.
|
291 |
|
292 | ## Maintainer
|
293 |
|
294 | - [Sindre Sorhus](https://github.com/sindresorhus)
|
295 | - [Caesarovich](https://github.com/Caesarovich)
|
296 |
|
297 | ## Related
|
298 |
|
299 | - [boxen-cli](https://github.com/sindresorhus/boxen-cli) - CLI for this module
|
300 | - [cli-boxes](https://github.com/sindresorhus/cli-boxes) - Boxes for use in the terminal
|