0
# Lodash Truncate
1

2
Lodash Truncate provides intelligent string truncation with comprehensive Unicode support and flexible formatting options. It safely shortens text to specified lengths while preserving word boundaries and supporting complex Unicode characters including astral plane characters, combining marks, and zero-width joiners.
3

4
## Package Information
5

6
- **Package Name**: lodash.truncate
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash.truncate`
10

11
## Core Imports
12

13
```javascript
14
const truncate = require('lodash.truncate');
15
```
16

17
For ES modules:
18

19
```javascript
20
import truncate from 'lodash.truncate';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const truncate = require('lodash.truncate');
27

28
// Basic truncation (default: 30 characters with '...')
29
truncate('hi-diddly-ho there, neighborino');
30
// => 'hi-diddly-ho there, neighbo...'
31

32
// Custom length
33
truncate('hi-diddly-ho there, neighborino', { length: 24 });
34
// => 'hi-diddly-ho there, nei...'
35

36
// Smart word boundary truncation
37
truncate('hi-diddly-ho there, neighborino', {
38
  length: 24,
39
  separator: ' '
40
});
41
// => 'hi-diddly-ho there,...'
42

43
// Custom omission indicator
44
truncate('hi-diddly-ho there, neighborino', {
45
  omission: ' [...]'
46
});
47
// => 'hi-diddly-ho there, neig [...]'
48
```
49

50
## Capabilities
51

52
### String Truncation
53

54
Truncates strings to a specified length with intelligent Unicode handling and configurable formatting options.
55

56
```javascript { .api }
57
/**
58
 * Truncates string if it's longer than the given maximum string length.
59
 * The last characters of the truncated string are replaced with the omission
60
 * string which defaults to "...".
61
 * 
62
 * @param {string} [string=''] - The string to truncate
63
 * @param {Object} [options={}] - The options object
64
 * @param {number} [options.length=30] - The maximum string length
65
 * @param {string} [options.omission='...'] - The string to indicate text is omitted
66
 * @param {RegExp|string} [options.separator] - The separator pattern to truncate to
67
 * @returns {string} Returns the truncated string
68
 */
69
function truncate(string, options);
70
```
71

72
**Parameters:**
73

74
- **string** (string, optional, default=''): The string to truncate. Any non-string value will be converted to string.
75
- **options** (Object, optional, default={}): Configuration object with the following properties:
76
  - **length** (number, optional, default=30): The maximum string length for the truncated result
77
  - **omission** (string, optional, default='...'): String to append to indicate text was omitted
78
  - **separator** (RegExp|string, optional): Pattern to truncate at for smart word/phrase boundary handling
79

80
**Returns:** (string) The truncated string, or the original string if no truncation was needed.
81

82
**Key Features:**
83

84
- **Unicode Support**: Properly handles astral plane characters, combining marks, and zero-width joiners
85
- **Smart Truncation**: When separator is provided, truncates at word/phrase boundaries instead of character boundaries
86
- **Flexible Separators**: Supports both string patterns and regular expressions for separator matching
87
- **Type Coercion**: Automatically converts non-string inputs to strings before processing
88
- **Precision Length Calculation**: Uses Unicode-aware length calculation for accurate character counting
89

90
**Usage Examples:**
91

92
```javascript
93
// Unicode string handling
94
truncate('🇺🇸👨‍👩‍👧‍👦 Family emoji test', { length: 10 });
95
// Properly handles complex emoji sequences
96

97
// Regular expression separator
98
truncate('one, two, three, four, five', {
99
  length: 20,
100
  separator: /,\s*/
101
});
102
// => 'one, two, three...'
103

104
// String separator for word boundaries
105
truncate('The quick brown fox jumps over the lazy dog', {
106
  length: 25,
107
  separator: ' '
108
});
109
// => 'The quick brown fox...'
110

111
// Custom omission with length consideration
112
truncate('Hello world this is a test', {
113
  length: 15,
114
  omission: '...'
115
});
116
// => 'Hello world...' (omission length is included in total length)
117

118
// No truncation needed
119
truncate('Short text', { length: 50 });
120
// => 'Short text' (returned unchanged)
121

122
// Edge case: omission longer than allowed length
123
truncate('Hello', { length: 2, omission: '...' });
124
// => '...' (returns just the omission when content can't fit)
125
```
126

127
## Types
128

129
```javascript { .api }
130
// Options interface (TypeScript representation for documentation)
131
interface TruncateOptions {
132
  length?: number;        // Maximum string length (default: 30)
133
  omission?: string;      // Text to indicate truncation (default: '...')
134
  separator?: RegExp | string;  // Pattern for smart boundary truncation
135
}
136
```