CLI Column Formatter

4.0.0 · active · verified Wed Apr 22

cli-columns is a lightweight Node.js utility designed to format arrays of strings into neatly aligned, columnated lists suitable for command-line interfaces. It is particularly noted for its robust handling of both Unicode characters and ANSI escape codes (e.g., for colored text) by accurately calculating visible widths, preventing visual misalignment common in other simpler columnizers. The current stable version is 4.0.0, which notably addressed a ReDoS vulnerability in its upstream dependencies and updated its minimum Node.js requirement to version 10 or higher. While its release cadence may appear measured, the project prioritizes stability and precise rendering for CLI output. Key differentiators include customizable padding characters, column spacing, newline characters, optional sorting, and the ability to set a maximum output width, often defaulting to `process.stdout.columns`.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use `require()` syntax in an ES Module context (e.g., a file with `"type": "module"` in `package.json` or a `.mjs` file).

fix Change the import statement to `import columns from 'cli-columns';` in your ES module file.
```
TypeError: cli_columns is not a function
```
cause Incorrectly importing the `columns` function using named import syntax (`import { columns } from 'cli-columns';`) when it's exported as a default.

fix Use the correct default import syntax: `import columns from 'cli-columns';`.
```
Error: The 'values' argument must be an Array<String>
```
cause Providing a non-array or an array containing non-string elements to the `columns` function. The library expects an array of strings.

fix Ensure the argument passed to `columns()` is an array where all elements are strings. For example: `columns(['string1', 'string2'])`.

Warnings

breaking Version 4.0.0 of `cli-columns` now requires Node.js version 10 or greater. Projects running on older Node.js versions must upgrade their environment or stick to `cli-columns@3.x`.
Fix: Upgrade Node.js to version 10 or higher, or explicitly install `cli-columns@3.x` if older Node.js versions are unavoidable (e.g., `npm install cli-columns@3`).
breaking Version 4.0.0 includes updated dependencies to address an upstream Regular Expression Denial of Service (ReDoS) vulnerability. Older versions of `cli-columns` (prior to 4.0.0) may be exposed to this vulnerability through their transitive dependencies.
Fix: Upgrade to `cli-columns@4.0.0` or newer to ensure you have the patched dependencies. Run `npm install cli-columns@latest`.

Install

npm install cli-columns npm
yarn add cli-columns yarn
pnpm add cli-columns pnpm

Imports

columns
wrong:
```
import { columns } from 'cli-columns';
```
correct:
```
import columns from 'cli-columns';
```
The 'columns' function is the default export. Using named import 'cli-columns' might result in undefined in some ESM environments.
columns
wrong:
```
const { columns } = require('cli-columns');
```
correct:
```
const columns = require('cli-columns');
```
In CommonJS, the module exports the 'columns' function directly as its default export.
columns
wrong:
```
import * as cliColumns from 'cli-columns'; const columns = cliColumns.default;
```
correct:
```
import columns from 'cli-columns';
```
While 'import * as' can work, the direct default import is cleaner and more idiomatic for this module's export style.

Quickstart

Demonstrates basic usage of `cli-columns` to format a list of strings, including those with Unicode and ANSI colors, into columns. It also shows how to customize width, sorting, and padding.

import columns from 'cli-columns';
import chalk from 'chalk';

const values = [
    'blue' + chalk.bgBlue('berry'),
    '笔菠萝' + chalk.yellow('苹果笔'),
    chalk.red('apple'), 'pomegranate',
    'durian', chalk.green('star fruit'),
    'パイナップル', 'apricot', 'banana',
    'pineapple', chalk.bgRed.yellow('orange'),
    'long-long-item-that-will-wrap-if-width-is-too-small'
];

// Basic usage, uses process.stdout.columns for width
console.log('--- Default Columnation ---');
console.log(columns(values));

// Custom width and no sorting
console.log('\n--- Custom Width (40) & Unsorted ---');
console.log(columns(values, { width: 40, sort: false }));

// Custom padding character
console.log('\n--- Custom Padding Character (".") ---');
console.log(columns(values, { character: '.' }));

view raw JSON →