sindresorhus / cli-truncate

Truncate a string to a specific width in the terminal

cli-truncate

Truncate a string to a specific width in the terminal

Gracefully handles ANSI escapes. Like a string styled with chalk. It also supports Unicode surrogate pairs and fullwidth characters.

Install

npm install cli-truncate

Usage

import cliTruncate from 'cli-truncate';

cliTruncate('unicorn', 4);
//=> 'uni…'

// Truncate at different positions
cliTruncate('unicorn', 4, {position: 'start'});
//=> '…orn'

cliTruncate('unicorn', 4, {position: 'middle'});
//=> 'un…n'

cliTruncate('unicorns rainbow dragons', 6, {position: 'end'})
//=> 'unico…'

cliTruncate('\u001B[31municorn\u001B[39m', 4);
//=> '\u001B[31muni\u001B[39m…'

// Truncate Unicode surrogate pairs
cliTruncate('uni\uD83C\uDE00corn', 5);
//=> 'uni\uD83C\uDE00…'

// Truncate fullwidth characters
cliTruncate('안녕하세요', 3);
//=> '안…'

// Truncate the paragraph to the terminal width
const paragraph = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa.';
cliTruncate(paragraph, process.stdout.columns);
//=> 'Lorem ipsum dolor sit amet, consectetuer adipiscing…'

API

cliTruncate(text, columns, options?)

text

Type: string

The text to truncate.

columns

Type: number

The number of columns to occupy in the terminal.

options

Type: object

position

Type: string
Default: 'end'
Values: 'start' | 'middle' | 'end'

The position to truncate the string.

space

Type: boolean
Default: false

Add a space between the text and the ellipsis.

import cliTruncate from 'cli-truncate';

cliTruncate('unicorns', 5, {space: false});
//=> 'unic…'

cliTruncate('unicorns', 5, {space: true});
//=> 'uni …'

cliTruncate('unicorns', 6, {position: 'start', space: true});
//=> '… orns'

cliTruncate('unicorns', 7, {position: 'middle', space: true});
//=> 'uni … s'

preferTruncationOnSpace

Type: boolean
Default: false

Truncate the string from a whitespace if it is within 3 characters from the actual breaking point.

import cliTruncate from 'cli-truncate';

cliTruncate('unicorns rainbow dragons', 20, {position: 'start', preferTruncationOnSpace: true})
//=> '…rainbow dragons'

// without preferTruncationOnSpace
cliTruncate('unicorns rainbow dragons', 20, {position: 'start'})
//=> '…rns rainbow dragons'

cliTruncate('unicorns rainbow dragons', 20, {position: 'middle', preferTruncationOnSpace: true})
//=> 'unicorns…dragons'

cliTruncate('unicorns rainbow dragons', 6, {position: 'end', preferTruncationOnSpace: true})
//=> 'unico…'

// preferTruncationOnSpace would have no effect if space isn't found within next 3 indexes
cliTruncate('unicorns rainbow dragons', 6, {position: 'middle', preferTruncationOnSpace: true})
//=> 'uni…ns'

truncationCharacter

Type: string
Default: …

The character to use at the breaking point.

import cliTruncate from 'cli-truncate';

cliTruncate('unicorns', 5, {position: 'end'});
//=> 'unic…'

cliTruncate('unicorns', 5, {position: 'end', truncationCharacter: '.'});
//=> 'unic.'

cliTruncate('unicorns', 5, {position: 'end', truncationCharacter: ''});
//=> 'unico'

Related

• wrap-ansi - Wordwrap a string with ANSI escape codes
• slice-ansi - Slice a string with ANSI escape codes

cli-truncate's Issues

add option to let user choose how many characters left in front and in end, if position is middle

currently if set position middle, the tool slice half of columns length in front and another half at end.

Use other character (or no character) instead of elipsis

This is a great tool, but the one thing preventing me from using it the fact that in my use case i'd like the text to be truncated w/o an ellipsis.

Could we have an option truncateChar or so that allows us replace the ellipsis with another character (or none at all)?

Option to choose where to truncate

Currently it's truncated at the end, but an option could enable truncating at the start or in the middle.

Not something I need right now, but might be useful in the future.

A good pull request would be much welcome :)

Automatic style detection

It'd be cool, although probably a bit unnecessary and overcomplicated, if for example when truncating at the end the style of the character preceding the ellipses is detected and the ellipsis is written using the same style.

Truncates more characters than necessary

Reproduction from the readme:

cliTruncate('unicorn', 4);
//=> 'un…', not 'uni…'

Can be reproduced without any changes by pulling a fresh clone of this repository and running npm test.

❯ npm t

> [email protected] test
> xo && ava && tsd


  main

  Difference:

  - 'un…'
  + 'uni…'

  › file://test.js:5:4



  space option

  Difference:

  - 'un …'
  + 'uni …'

  › file://test.js:25:4

  ─

  2 tests failed

I reverted 23b40dc locally and tests are passing now, so it has to be a regression from #19. cc @codemaster138

Some graphemes (e.g. country flags) break the truncation invariant

Considering cli-truncate works with terminal char widths, I think this expectation is valid:
expect(cliTruncate('🇪🇺!', 2)).toEqual('…')

However due to country flags consisting of multiple code points treated as separate chars in slice-ansi, cliTruncate returns "🇪…"

This is not only rendering artifact but a broken invariant, e.g. string-width stringWidth("🇪…") returns 3 that is above requested width 2.

using Intl.Segmenter in slice-ansi can be possible way to fix it: chalk/slice-ansi#35

Got here debugging ink truncation issue when line had country flag on box wrap edge)

Support fullwidth characters and unicode surrogate pairs

cli-truncate/test.js

Lines 15 to 17 in dbc522d

	// TODO
	t.skip.is(m('a\ud83c\ude00b\ud83c\ude00c', 5), 'a\ud83c\ude00b…', 'surrogate pairs');
	t.skip.is(m('안녕하세요', 3), '안…', 'wide char');

Depends on chalk/wrap-ansi#10 and chalk/wrap-ansi#11.

Note to self: Update the readme description when this is fixed.

Must use import to load ES Module

Hello,

I just installed this package, which by the way, seems to be the only one that does truncation and is currently maintained.

However, I have an issue while using this package inside my Next.Js application (in Typescript).

Here is how I import the package :

import cliTruncate from "cli-truncate";
// I also tried
import * as cliTruncate from "cli-truncate";

And here is the error on runtime:

Error: Must use import to load ES Module: D:\workspace\my-app\node_modules\cli-truncate\index.js
require() of ES modules is not supported.
require() of D:\workspace\my-app\node_modules\cli-truncate\index.js from D:\workspace\my-app\packages\website\.next\server\pages\blog.js is an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which defines all .js files in that package scope as ES modules.
Instead rename index.js to end in .cjs, change the requiring code to use import(), or remove "type": "module" from D:\workspace\my-app\node_modules\cli-truncate\package.json.

Do you have any idea why is this happening?

Add option to prefer truncating on spaces if possible

See: sindresorhus/fkill-cli#47 (comment)

---

IssueHunt Summary

ammarbinfaisal has been rewarded.

Sponsors (Total: $40.00)

• issuehunt ($40.00)

Tips

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on IssueHunt to raise funds.

Ellipsis color is always white

Hi,

in cliTruncate( chalk.gray( someLongFileName ), process.stdout.columns, { position: 'middle' } ) the ellipsis color is white (not gray).

Better having a color property in the options, like { position: 'middle', color: 'gray' } ?

Note: tested only on Win10

Add option to add a space either side of ellipsis

An option to add a space either side of the ellipsis would be nice. thanks

satyarohith earned $30.00 by resolving this issue!

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on Issuehunt to raise funds.