truncate function

Shortens a string to a maximum length, with an ellipsis when it is cut. An emoji or an accented letter counts as one character and is never split.

import { truncate } from 'utils';

Signature

export function truncate(input: string, maxLength: number, ellipsis = '…'): string

Parameters

Name	Description
input	The string to shorten.
maxLength	The largest length of the result, ellipsis included.
ellipsis	The text appended when the string is cut. Defaults to '…'.

Returns

The string itself when it fits, the cut string with its ellipsis otherwise.

Example

truncate('Engine room temperature', 12); // 'Engine room…'
truncate('Short', 12); // 'Short'
truncate('Engine room temperature', 12, '...'); // 'Engine ro...'

Tests

Line coverage: 100 %.

• ✅ truncates "Engine room temperature" to 12 characters
• ✅ truncates "Short" to 12 characters
• ✅ truncates "Exactly12chr" to 12 characters
• ✅ truncates "🚢🚢🚢🚢" to 3 characters
• ✅ truncates "🇫🇷🇫🇷🇫🇷" to 2 characters
• ✅ truncates "abc" to 0 characters
• ✅ uses a custom ellipsis

Source

src/string/truncate.ts (on GitHub)

Source code

const graphemeSegmenter = new Intl.Segmenter();

function graphemes(text: string): string[] {
  return Array.from(graphemeSegmenter.segment(text), (part) => part.segment);
}

/**
 * Shortens a string to a maximum length, with an ellipsis when it is cut. An emoji or an accented letter
 * counts as one character and is never split.
 *
 * @param input - The string to shorten.
 * @param maxLength - The largest length of the result, ellipsis included.
 * @param ellipsis - The text appended when the string is cut. Defaults to `'…'`.
 * @returns The string itself when it fits, the cut string with its ellipsis otherwise.
 * @example
 * truncate('Engine room temperature', 12); // 'Engine room…'
 * truncate('Short', 12); // 'Short'
 * truncate('Engine room temperature', 12, '...'); // 'Engine ro...'
 */
export function truncate(input: string, maxLength: number, ellipsis = '…'): string {
  const characters = graphemes(input);
  if (characters.length <= maxLength) {
    return input;
  }
  const ellipsisCharacters = graphemes(ellipsis);
  return ellipsisCharacters.length >= maxLength
    ? ellipsisCharacters.slice(0, maxLength).join('')
    : characters.slice(0, maxLength - ellipsisCharacters.length).join('') + ellipsis;
}

Test file

import { truncate } from './truncate';

describe(truncate, () => {
  it.for([
    ['Engine room temperature', 12, 'Engine room…'],
    ['Short', 12, 'Short'],
    ['Exactly12chr', 12, 'Exactly12chr'],
    ['🚢🚢🚢🚢', 3, '🚢🚢…'],
    ['🇫🇷🇫🇷🇫🇷', 2, '🇫🇷…'],
    ['abc', 0, ''],
  ] as const)('truncates %j to %s characters', ([input, maxLength, expected]) => {
    expect(truncate(input, maxLength, '…')).toBe(expected);
  });

  it('uses a custom ellipsis', () => {
    expect(truncate('Engine room temperature', 12, '...')).toBe('Engine ro...');
    expect(truncate('Engine room temperature', 2, '...')).toBe('..');
  });
});

Keywords: truncate, strings, function