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 |
|
115 | Style of the box border.
|
116 |
|
117 | Can be any of the above predefined styles or an object with the following keys:
|
118 |
|
119 | ```js
|
120 | {
|
121 | topLeft: '+',
|
122 | topRight: '+',
|
123 | bottomLeft: '+',
|
124 | bottomRight: '+',
|
125 | horizontal: '-',
|
126 | vertical: '|'
|
127 | }
|
128 | ```
|
129 |
|
130 | ##### dimBorder
|
131 |
|
132 | Type: `boolean`\
|
133 | Default: `false`
|
134 |
|
135 | Reduce opacity of the border.
|
136 |
|
137 | ##### title
|
138 |
|
139 | Type: `string`
|
140 |
|
141 | Display a title at the top of the box.
|
142 | If needed, the box will horizontally expand to fit the title.
|
143 |
|
144 | Example:
|
145 | ```js
|
146 | console.log(boxen('foo bar', {title: 'example'}));
|
147 | /*
|
148 | ┌ example ┐
|
149 | │foo bar │
|
150 | └─────────┘
|
151 | */
|
152 | ```
|
153 |
|
154 | ##### titleAlignment
|
155 |
|
156 | Type: `string`\
|
157 | Default: `'left'`
|
158 |
|
159 | Align the title in the top bar.
|
160 |
|
161 | Values:
|
162 | - `'left'`
|
163 | ```js
|
164 | /*
|
165 | ┌ example ──────┐
|
166 | │foo bar foo bar│
|
167 | └───────────────┘
|
168 | */
|
169 | ```
|
170 | - `'center'`
|
171 | ```js
|
172 | /*
|
173 | ┌─── example ───┐
|
174 | │foo bar foo bar│
|
175 | └───────────────┘
|
176 | */
|
177 | ```
|
178 | - `'right'`
|
179 | ```js
|
180 | /*
|
181 | ┌────── example ┐
|
182 | │foo bar foo bar│
|
183 | └───────────────┘
|
184 | */
|
185 | ```
|
186 |
|
187 | ##### padding
|
188 |
|
189 | Type: `number | object`\
|
190 | Default: `0`
|
191 |
|
192 | Space between the text and box border.
|
193 |
|
194 | 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.
|
195 |
|
196 | ##### margin
|
197 |
|
198 | Type: `number | object`\
|
199 | Default: `0`
|
200 |
|
201 | Space around the box.
|
202 |
|
203 | 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.
|
204 |
|
205 | ##### float
|
206 |
|
207 | Type: `string`\
|
208 | Default: `'left'`\
|
209 | Values: `'right'` `'center'` `'left'`
|
210 |
|
211 | Float the box on the available terminal screen space.
|
212 |
|
213 | ##### backgroundColor
|
214 |
|
215 | Type: `string`\
|
216 | Values: `'black'` `'red'` `'green'` `'yellow'` `'blue'` `'magenta'` `'cyan'` `'white'` `'gray'` or a hex value like `'#ff0000'`
|
217 |
|
218 | Color of the background.
|
219 |
|
220 | ##### textAlignment
|
221 |
|
222 | Type: `string`\
|
223 | Default: `'left'`\
|
224 | Values: `'left'` `'center'` `'right'`
|
225 |
|
226 | Align the text in the box based on the widest line.
|
227 |
|
228 | ## Maintainer
|
229 |
|
230 | - [Sindre Sorhus](https://github.com/sindresorhus)
|
231 | - [Caesarovich](https://github.com/Caesarovich)
|
232 |
|
233 | ## Related
|
234 |
|
235 | - [boxen-cli](https://github.com/sindresorhus/boxen-cli) - CLI for this module
|
236 | - [cli-boxes](https://github.com/sindresorhus/cli-boxes) - Boxes for use in the terminal
|
237 | - [ink-box](https://github.com/sindresorhus/ink-box) - Box component for Ink that uses this package
|
238 |
|
239 | ---
|
240 |
|
241 | <div align="center">
|
242 | <b>
|
243 | <a href="https://tidelift.com/subscription/pkg/npm-boxen?utm_source=npm-boxen&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
|
244 | </b>
|
245 | <br>
|
246 | <sub>
|
247 | Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
|
248 | </sub>
|
249 | </div>
|