# @topcli/cliui

> easily create complex multi-column command-line-interfaces

Latest version **1.1.0** (published 2022-12-23) · ISC license · 0 weekly downloads

## Install

```sh
npm install @topcli/cliui
pnpm add @topcli/cliui
yarn add @topcli/cliui
bun add @topcli/cliui
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2022-12-23 |
| First published | 2022-12-23 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=16.16 |
| Dependencies | 3 |
| Unpacked size | 15.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Ben Coe |
| Maintainers | pierred, fraxken |
| Keywords | cli, command-line, layout, design, console, wrap, table |

## Links

- npm: https://www.npmjs.com/package/@topcli/cliui
- Repository: https://github.com/TopCli/cliui
- Homepage: https://github.com/TopCli/cliui#readme
- Issues: https://github.com/TopCli/cliui/issues
- npm.io page: https://npm.io/package/@topcli/cliui

## Dependencies (3)

- [wrap-ansi](https://npm.io/package/wrap-ansi.md) ^7.0.0
- [strip-ansi](https://npm.io/package/strip-ansi.md) ^6.0.1
- [@topcli/wcwidth](https://npm.io/package/@topcli/wcwidth.md) ^1.0.0

## Alternatives

- [@lexical/table](https://npm.io/package/@lexical/table.md) — 3.0M weekly downloads
- [mantine-datatable](https://npm.io/package/mantine-datatable.md) — 98.2K weekly downloads
- [react-native-collapsible-tab-view](https://npm.io/package/react-native-collapsible-tab-view.md) — 70.6K weekly downloads
- [@handsontable/vue3](https://npm.io/package/@handsontable/vue3.md) — 16.1K weekly downloads
- [vuewordcloud](https://npm.io/package/vuewordcloud.md) — 7.2K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2022-12-23

## README

# cliui

easily create complex multi-column command-line-interfaces.

## Example

> **Note** This package is ESM only.

```js
import cliui from '@topcli/cli';

const ui = cliui();

ui.div('Usage: $0 [command] [options]')

ui.div({
  text: 'Options:',
  padding: [2, 0, 1, 0]
})

ui.div(
  {
    text: "-f, --file",
    width: 20,
    padding: [0, 4, 0, 4]
  },
  {
    text: "the file to load." +
      chalk.green("(if this description is long it wraps).")
    ,
    width: 20
  },
  {
    text: chalk.red("[required]"),
    align: 'right'
  }
)

console.log(ui.toString())
```

<img width="500" src="public/screenshot.png">

## Layout DSL

cliui exposes a simple layout DSL:

If you create a single `ui.div`, passing a string rather than an
object:

* `\n`: characters will be interpreted as new rows.
* `\t`: characters will be interpreted as new columns.
* `\s`: characters will be interpreted as padding.

**as an example...**

```js
import cliui from '@topcli/cli';

const ui = cliui({
  width: 60
})

ui.div(
  'Usage: node ./bin/foo.js\n' +
  '  <regex>\t  provide a regex\n' +
  '  <glob>\t  provide a glob\t [required]'
)

console.log(ui.toString())
```

**will output:**

```shell
Usage: node ./bin/foo.js
  <regex>  provide a regex
  <glob>   provide a glob          [required]
```

## Methods

### cliui({width: integer})

Specify the maximum width of the UI being generated.
If 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`.

### cliui({wrap: boolean})

Enable or disable the wrapping of text in a column.

### cliui.div(column, column, column)

Create a row with any number of columns, a column
can either be a string, or an object with the following
options:

* **text:** some text to place in the column.
* **width:** the width of a column.
* **align:** alignment, `right` or `center`.
* **padding:** `[top, right, bottom, left]`.
* **border:** should a border be placed around the div?

### cliui.span(column, column, column)

Similar to `div`, except the next row will be appended without
a new line being created.

### cliui.resetOutput()

Resets the UI elements of the current cliui instance, maintaining the values
set for `width` and `wrap`.

---
_Source: https://npm.io/package/@topcli/cliui · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
