Miss any of our Open RFC calls?Watch the recordings here! »

cli-truncate

2.1.0 • Public • Published

cli-truncate Build Status

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

const cliTruncate = require('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

Text to truncate.

columns

Type: number

Columns to occupy in the terminal.

options

Type: object

position

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

Position to truncate the string.

space

Type: boolean
Default: false

Add a space between the text and the ellipsis.

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.

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'

Related

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

Get professional support for this package with a Tidelift subscription
Tidelift helps make open source sustainable for maintainers while giving companies
assurances about security, maintenance, and licensing for their dependencies.

Install

npm i cli-truncate

DownloadsWeekly Downloads

5,551,525

Version

2.1.0

License

MIT

Unpacked Size

10.4 kB

Total Files

5

Last publish

Collaborators

  • avatar