@kaelyx/ts-kit

Appearance

@kaelyx/ts-kit / string / truncate

Function: truncate() ​

truncate(input, length, options?): string

Defined in: string/truncate/truncate.ts:126

The truncate function shortens a string to a maximum length. It can add a suffix and cut at a word boundary.

By default, lengths are counted in grapheme clusters (user-visible characters). Set unit to count in UTF-16 code units or in UTF-8 bytes. In each unit, the function cuts only between graphemes, so it never splits an emoji or separates an accent from its letter. Trailing whitespace is removed from the cut text.

With the default unit, the result can have a .length that is more than length, because .length counts UTF-16 code units, not graphemes. For example, truncate('😀😀😀😀', 2) returns '😀😀', and its .length is 4. Choose the unit for the limit that you must fit:

  • 'grapheme' for text that people read, for example a label or a preview.
  • 'codeUnit' for a limit on .length.
  • 'byte' for a limit in bytes, for example a database index or an HTTP header.

Parameters ​

input ​

string

The string to truncate. If the input already fits, the function returns it unchanged.

length ​

number

The maximum length of the result. If length is not an integer, the function rounds it down. If length is 0 or less, the function returns an empty string. If length is Infinity, the function returns the input.

options? ​

TruncateOptions

The suffix to add, whether the suffix counts towards length, whether to cut at a word boundary, and the unit that lengths count in. See TruncateOptions.

Returns ​

string

The truncated string, with the suffix if the input was cut.

Throws ​

If length is NaN.

Example ​

ts
truncate('hello world', 5) // 'hello'
truncate('hello world', 8, { append: '...' }) // 'hello...'
truncate('hello world', 5, { append: '...', includeAppendInLength: false }) // 'hello...'
truncate('hello world', 2, { append: '...' }) // 'he'
truncate('hello world foo', 13, { truncateAtWordBoundary: true }) // 'hello world'
truncate('hello world foo', 11, { truncateAtWordBoundary: true }) // 'hello world'
truncate('hello world', 6) // 'hello'
truncate('ab😀cd', 3) // 'ab😀'
truncate('café au lait', 4) // 'café'
truncate('hello world', 5.9) // 'hello'
truncate('hello world', Infinity) // 'hello world'
truncate('hello world', 0) // ''
truncate('hello world', NaN) // throws RangeError

// Units. The cut is always between graphemes, so the result can be shorter than length.
truncate('😀😀😀😀', 2) // '😀😀', and its .length is 4
truncate('😀😀😀😀', 2, { unit: 'grapheme' }) // '😀😀'
truncate('😀😀😀😀', 2, { unit: 'codeUnit' }) // '😀'
truncate('café', 4, { unit: 'byte' }) // 'caf', because 'é' is 2 bytes
truncate('👨‍👩‍👧', 2, { unit: 'codeUnit' }) // '', because the first grapheme is 8 code units

Types ​

TruncateOptions interface ​

Defined in: string/truncate/truncate.types.ts:11

Options for truncate.

All lengths are counted in unit. The default unit is grapheme clusters (user-visible characters), not UTF-16 code units.

Properties ​

append? ​

readonly optional append?: string

Defined in: string/truncate/truncate.types.ts:16

The suffix to add after the cut text. It is only added when the input is cut.

Default ​
ts
''
includeAppendInLength? ​

readonly optional includeAppendInLength?: boolean

Defined in: string/truncate/truncate.types.ts:24

Count the suffix towards length, so that the result is never longer than length. If the suffix is longer than length, the result is the cut text without the suffix. Set to false to add the suffix after length characters.

Default ​
ts
true
truncateAtWordBoundary? ​

readonly optional truncateAtWordBoundary?: boolean

Defined in: string/truncate/truncate.types.ts:31

Cut at the last whitespace before the limit instead of in the middle of a word. If there is no whitespace before the limit, the text is cut at the limit.

Default ​
ts
false
unit? ​

readonly optional unit?: "grapheme" | "codeUnit" | "byte"

Defined in: string/truncate/truncate.types.ts:46

The unit that length and the length of append count in.

  • 'grapheme': grapheme clusters (user-visible characters).
  • 'codeUnit': UTF-16 code units, the unit of .length.
  • 'byte': bytes when the text is encoded as UTF-8.

The cut is always between graphemes, and the function never cuts a grapheme. Thus the result can be shorter than length, and the result can be empty. For example, with unit: 'codeUnit' and a length of 2, '👨‍👩‍👧' gives '', because the grapheme has 8 code units.

Default ​
ts
'grapheme'