CLI Truncate

6.0.0 · active · verified Wed Apr 22

cli-truncate is a JavaScript library designed for precisely truncating strings within a terminal environment, correctly accounting for the visual width occupied by characters, including those with ANSI escape codes (like colors and styles), Unicode surrogate pairs, and fullwidth characters. The current stable version is 6.0.0, which requires Node.js 22.x or later. The package has a consistent release cadence, often introducing new major versions to align with updated Node.js engine requirements, alongside minor and patch releases for bug fixes and feature enhancements. Its key differentiators lie in its robust handling of terminal-specific challenges: it ensures that styled text, such as output from `chalk`, is truncated accurately without breaking formatting, and it correctly measures the width of complex Unicode characters that standard `String.prototype.slice` or similar methods would misinterpret. It offers flexible truncation positions (start, middle, end) and options like `space` for adding a gap before the ellipsis and `preferTruncationOnSpace` to attempt truncation at a word boundary for better readability.

Common errors

```
ERR_REQUIRE_ESM: require() of ES Module /path/to/node_modules/cli-truncate/index.js from /your/project/file.js not supported.
```
cause Attempting to use `require()` to import `cli-truncate`, which is an ES Module.

fix Change your import statement to `import cliTruncate from 'cli-truncate';`. Ensure your `package.json` has `'type': 'module'` or use `.mjs` file extension for your source file.
```
The 'cli-truncate' package is not compatible with your current Node.js version. Required: '>=22'
```
cause Running `cli-truncate` v6.0.0 (or a similar version) with an older Node.js runtime.

fix Upgrade your Node.js installation to version 22 or higher. Alternatively, install an older major version of `cli-truncate` that is compatible with your current Node.js version (e.g., `npm install cli-truncate@5` for Node.js 20).

Warnings

breaking Node.js 22 or later is now required for `cli-truncate` v6.0.0.
Fix: Upgrade your Node.js environment to version 22 or higher, or downgrade `cli-truncate` to a compatible major version (e.g., v5 for Node.js 20, v4 for Node.js 18).
breaking `cli-truncate` migrated to pure ESM (ECMAScript Modules). CommonJS `require()` is no longer supported.
Fix: Update your import statements from `const cliTruncate = require('cli-truncate');` to `import cliTruncate from 'cli-truncate';`. Ensure your project is configured for ESM, potentially by adding `'type': 'module'` to your `package.json` or by using `.mjs` file extensions.
breaking Node.js 20 or later is required for `cli-truncate` v5.0.0.
Fix: Upgrade your Node.js environment to version 20 or higher, or downgrade `cli-truncate` to v4 if you need Node.js 18 support.
breaking Node.js 18 or later is required for `cli-truncate` v4.0.0.
Fix: Upgrade your Node.js environment to version 18 or higher, or downgrade `cli-truncate` to v3 if you need Node.js 12.20+ support.
gotcha When using ANSI escape codes (e.g., with `chalk`), `cli-truncate` attempts to inherit the style for the truncation character. For `position: 'middle'`, the truncation character does not inherit surrounding ANSI styles.
Fix: Be aware of this specific styling behavior if precise style continuity for the ellipsis in `position: 'middle'` is critical to your output design.

Install

npm install cli-truncate npm
yarn add cli-truncate yarn
pnpm add cli-truncate pnpm

Imports

cliTruncate
wrong:
```
const cliTruncate = require('cli-truncate');
```
correct:
```
import cliTruncate from 'cli-truncate';
```
The package has been pure ESM since v3.0.0. CommonJS `require()` is not supported.
cliTruncate (TypeScript)
```
import cliTruncate from 'cli-truncate';
```
TypeScript types are included and automatically picked up when importing.
Options (TypeScript Type)
```
import type { Options } from 'cli-truncate';
```
For type-only imports in TypeScript, use the `import type` syntax.

Quickstart

Demonstrates truncating a long paragraph to the current terminal width, gracefully handling character widths and potential ANSI escape codes, for clean console output. It also shows using `preferTruncationOnSpace` for better readability.

import cliTruncate from 'cli-truncate';

const paragraph = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.';

// Truncate a long string to the current terminal width, or 80 columns if not available.
const terminalWidth = process.stdout.columns ?? 80;
const truncatedText = cliTruncate(paragraph, terminalWidth, { position: 'end', preferTruncationOnSpace: true });

console.log('Original length:', paragraph.length);
console.log('Truncated length (visual):', truncatedText.length);
console.log('Truncated text:', truncatedText);

view raw JSON →