1# cliui
2
3![ci](https://github.com/yargs/cliui/workflows/ci/badge.svg)
4[![NPM version](https://img.shields.io/npm/v/cliui.svg)](https://www.npmjs.com/package/cliui)
5[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
6![nycrc config on GitHub](https://img.shields.io/nycrc/yargs/cliui)
7
8easily create complex multi-column command-line-interfaces.
9
10## Example
11
12```js
13const ui = require('cliui')()
14
15ui.div('Usage: $0 [command] [options]')
16
17ui.div({
18  text: 'Options:',
19  padding: [2, 0, 1, 0]
20})
21
22ui.div(
23  {
24    text: "-f, --file",
25    width: 20,
26    padding: [0, 4, 0, 4]
27  },
28  {
29    text: "the file to load." +
30      chalk.green("(if this description is long it wraps).")
31    ,
32    width: 20
33  },
34  {
35    text: chalk.red("[required]"),
36    align: 'right'
37  }
38)
39
40console.log(ui.toString())
41```
42
43## Deno/ESM Support
44
45As of `v7` `cliui` supports [Deno](https://github.com/denoland/deno) and
46[ESM](https://nodejs.org/api/esm.html#esm_ecmascript_modules):
47
48```typescript
49import cliui from "https://deno.land/x/cliui/deno.ts";
50
51const ui = cliui({})
52
53ui.div('Usage: $0 [command] [options]')
54
55ui.div({
56  text: 'Options:',
57  padding: [2, 0, 1, 0]
58})
59
60ui.div({
61  text: "-f, --file",
62  width: 20,
63  padding: [0, 4, 0, 4]
64})
65
66console.log(ui.toString())
67```
68
69<img width="500" src="screenshot.png">
70
71## Layout DSL
72
73cliui exposes a simple layout DSL:
74
75If you create a single `ui.div`, passing a string rather than an
76object:
77
78* `\n`: characters will be interpreted as new rows.
79* `\t`: characters will be interpreted as new columns.
80* `\s`: characters will be interpreted as padding.
81
82**as an example...**
83
84```js
85var ui = require('./')({
86  width: 60
87})
88
89ui.div(
90  'Usage: node ./bin/foo.js\n' +
91  '  <regex>\t  provide a regex\n' +
92  '  <glob>\t  provide a glob\t [required]'
93)
94
95console.log(ui.toString())
96```
97
98**will output:**
99
100```shell
101Usage: node ./bin/foo.js
102  <regex>  provide a regex
103  <glob>   provide a glob          [required]
104```
105
106## Methods
107
108```js
109cliui = require('cliui')
110```
111
112### cliui({width: integer})
113
114Specify the maximum width of the UI being generated.
115If no width is provided, cliui will try to get the current window's width and use it, and if that doesn't work, width will be set to `80`.
116
117### cliui({wrap: boolean})
118
119Enable or disable the wrapping of text in a column.
120
121### cliui.div(column, column, column)
122
123Create a row with any number of columns, a column
124can either be a string, or an object with the following
125options:
126
127* **text:** some text to place in the column.
128* **width:** the width of a column.
129* **align:** alignment, `right` or `center`.
130* **padding:** `[top, right, bottom, left]`.
131* **border:** should a border be placed around the div?
132
133### cliui.span(column, column, column)
134
135Similar to `div`, except the next row will be appended without
136a new line being created.
137
138### cliui.resetOutput()
139
140Resets the UI elements of the current cliui instance, maintaining the values
141set for `width` and `wrap`.
142