cliui

When passing a single string to ui.div(), you can use special characters to define the layout structure:

• \n: Interpreted as new rows.
• \t: Interpreted as new columns.
• \s: Interpreted as padding.

Example:

var ui = require('./')({
  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())

As of v7, cliui supports Deno and ECMAScript Modules (ESM).

import cliui from "cliui";
import chalk from "chalk";
// Deno: import cliui from "https://deno.land/x/cliui/deno.ts";

const ui = cliui({});
// ... usage same as CJS

Install cliui and chalk (for coloring) using npm:

npm i cliui@latest chalk@latest

Use cliui to build complex command-line interfaces with columns, padding, and alignment. You can pass strings or configuration objects to define rows and columns. Use .toString() to retrieve the final formatted string.

const ui = require('cliui')()
const {Chalk} = require('chalk');
const chalk = new Chalk();

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())

When initializing cliui(), you can pass a configuration object:

• width (integer): Specifies the maximum width of the UI. If not provided, it attempts to detect the window width, falling back to 80.
• wrap (boolean): Enables or disables text wrapping within a column.

const ui = cliui({ width: 60, wrap: true });

When initializing cliui, you can provide a UIOptions object to control the layout behavior:

• width (number): The total width of the layout. If not provided, it defaults to the terminal's column width (or 80 if unavailable).
• wrap (boolean, optional): Whether to enable word wrapping. Defaults to true if not specified.
• rows (string[], optional): Pre-defined rows for the UI.

The div() method is the primary way to add rows to your layout. It accepts an array of Column objects or plain strings.

If you pass a single string containing tabs (\t) and newlines (\n), cliui will automatically apply a Layout DSL to parse it into a table structure.

Column Object Properties:

• text (string): The content of the column.
• width (number, optional): Explicit width for the column.
• align ('right' | 'left' | 'center', optional): Horizontal alignment of text.
• padding (number[], optional): An array of 4 numbers representing [top, right, bottom, left] padding.
• border (boolean, optional): If true, renders a border around the column content.

ui.div(
  { text: 'Name', width: 10, border: true },
  { text: 'Value', align: 'right' }
);

// Using Layout DSL with a single string
ui.div("Name\tValue\nAlice\t10\nBob\t20");

In ESM environments, you can import the default export ui to initialize cliui with pre-configured dependencies for handling string widths, stripping ANSI escape codes, and wrapping ANSI-encoded text. This ensures consistent terminal output behavior.

import ui from 'cliui';

const layout = ui({
  // options for cliui
});

To get the final formatted string representation of your layout, call toString(). This method processes all rows, applies alignment, padding, borders, and word wrapping, and joins the lines into a single string. Lines marked as hidden are excluded from the output.

const output = ui.toString();
console.log(output);

To create a new UI instance for building CLI layouts, use the cliui function. It requires a mixin object containing utility functions for string manipulation and a partial UIOptions object.

Required Mixin Interface:

• stringWidth(str: string): number
• stripAnsi(str: string): string
• wrap(str: string, width: number, options: { hard: boolean }): string[]

import { cliui } from 'cliui';

// Example mixin implementation
const mixin = {
  stringWidth: (s) => s.length, // Simplified for example
  stripAnsi: (s) => s,
  wrap: (s, w) => [s].split('\n')
};

const ui = cliui({ width: 80, wrap: true }, mixin);

The resetOutput() method clears all currently defined rows in the UI instance, allowing you to reuse the same instance for a fresh layout.

ui.resetOutput();

Use the span() method to create a row that spans across the entire width of the layout. This is useful for headers or separators. It behaves like div() but marks the resulting columns as having span: true, which affects how they are rendered inline with subsequent rows.

ui.span('This is a full-width header');