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

1npm install cli-truncate

Usage

1import cliTruncate from 'cli-truncate';
2
3cliTruncate('unicorn', 4);
4//=> 'uni…'
5
6// Truncate at different positions
7cliTruncate('unicorn', 4, {position: 'start'});
8//=> '…orn'
9
10cliTruncate('unicorn', 4, {position: 'middle'});
11//=> 'un…n'
12
13cliTruncate('unicorns rainbow dragons', 6, {position: 'end'})
14//=> 'unico…'
15
16cliTruncate('\u001B[31municorn\u001B[39m', 4);
17//=> '\u001B[31muni\u001B[39m…'
18
19// Truncate Unicode surrogate pairs
20cliTruncate('uni\uD83C\uDE00corn', 5);
21//=> 'uni\uD83C\uDE00…'
22
23// Truncate fullwidth characters
24cliTruncate('안녕하세요', 3);
25//=> '안…'
26
27// Truncate the paragraph to the terminal width
28const paragraph = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa.';
29cliTruncate(paragraph, process.stdout.columns);
30//=> '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.

1import cliTruncate from 'cli-truncate';
2
3cliTruncate('unicorns', 5, {space: false});
4//=> 'unic…'
5
6cliTruncate('unicorns', 5, {space: true});
7//=> 'uni …'
8
9cliTruncate('unicorns', 6, {position: 'start', space: true});
10//=> '… orns'
11
12cliTruncate('unicorns', 7, {position: 'middle', space: true});
13//=> 'uni … s'

preferTruncationOnSpace

Type: boolean
Default: false

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

1import cliTruncate from 'cli-truncate';
2
3cliTruncate('unicorns rainbow dragons', 20, {position: 'start', preferTruncationOnSpace: true})
4//=> '…rainbow dragons'
5
6// without preferTruncationOnSpace
7cliTruncate('unicorns rainbow dragons', 20, {position: 'start'})
8//=> '…rns rainbow dragons'
9
10cliTruncate('unicorns rainbow dragons', 20, {position: 'middle', preferTruncationOnSpace: true})
11//=> 'unicorns…dragons'
12
13cliTruncate('unicorns rainbow dragons', 6, {position: 'end', preferTruncationOnSpace: true})
14//=> 'unico…'
15
16// preferTruncationOnSpace would have no effect if space isn't found within next 3 indexes
17cliTruncate('unicorns rainbow dragons', 6, {position: 'middle', preferTruncationOnSpace: true})
18//=> 'uni…ns'

truncationCharacter

Type: string
Default: …

The character to use at the breaking point.

1import cliTruncate from 'cli-truncate';
2
3cliTruncate('unicorns', 5, {position: 'end'});
4//=> 'unic…'
5
6cliTruncate('unicorns', 5, {position: 'end', truncationCharacter: '.'});
7//=> 'unic.'
8
9cliTruncate('unicorns', 5, {position: 'end', truncationCharacter: ''});
10//=> 'unico'

Related

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