0
# String Length
1

2
String Length provides accurate string length calculation by correctly counting Unicode astral symbols (like emojis) as single characters and optionally ignoring ANSI escape codes. Unlike JavaScript's native `String#length` which erroneously counts astral symbols as multiple characters, this library uses the modern `Intl.Segmenter` API for precise Unicode grapheme cluster segmentation.
3

4
## Package Information
5

6
- **Package Name**: string-length
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Module)
9
- **Installation**: `npm install string-length`
10

11
## Core Imports
12

13
```javascript
14
import stringLength from "string-length";
15
```
16

17
For TypeScript:
18

19
```typescript
20
import stringLength from "string-length";
21
import type { Options } from "string-length";
22
```
23

24
Note: This is an ES module only package. For CommonJS environments, use dynamic import:
25

26
```javascript
27
const { default: stringLength } = await import("string-length");
28
```
29

30
## Basic Usage
31

32
```javascript
33
import stringLength from "string-length";
34

35
// Standard JavaScript string length vs string-length
36
'🐴'.length;           // 2 (incorrect - counts UTF-16 code units)
37
stringLength('🐴');    // 1 (correct - counts visual character)
38

39
// ANSI escape codes are ignored by default
40
stringLength('\u001B[1municorn\u001B[22m');  // 7 (ignores ANSI codes)
41

42
// Complex Unicode sequences (emoji with skin tone modifiers)
43
stringLength('👊🏽');  // 1 (correct - single visual character)
44
```
45

46
## Capabilities
47

48
### String Length Calculation
49

50
Calculates the real visual length of a string by properly handling Unicode characters and ANSI escape codes.
51

52
```typescript { .api }
53
/**
54
 * Get the real length of a string by correctly counting astral symbols and ignoring ANSI escape codes
55
 * @param string - The input string to measure
56
 * @param options - Configuration options
57
 * @returns The visual character count
58
 */
59
export default function stringLength(string: string, options?: Options): number;
60
```
61

62
**Usage Examples:**
63

64
```javascript
65
import stringLength from "string-length";
66

67
// Unicode astral symbols (emojis, mathematical symbols)
68
stringLength('🐴');                    // 1
69
stringLength('𠀔');                    // 1 (CJK ideograph)
70
stringLength('foo𠁐bar𠀃');           // 8
71
stringLength('🏴󠁧󠁢󠁥󠁮󠁧󠁿❤️谢👪');      // 4 (complex emoji sequence)
72

73
// ANSI escape codes handling
74
stringLength('\u001B[1mfoo\u001B[22m');              // 3 (ignores ANSI by default)
75
stringLength('\u001B[1mfoo\u001B[22m', {
76
  countAnsiEscapeCodes: true
77
});                                                   // 12 (includes ANSI codes)
78

79
// Empty strings
80
stringLength('');                      // 0
81
stringLength('\u001B[1m\u001B[22m');   // 0 (only ANSI codes)
82

83
// Complex Unicode with modifiers
84
stringLength('👩‍👧‍👦');              // 1 (family emoji)
85
stringLength('❤️');                   // 1 (heart with variation selector)
86
```
87

88
## Types
89

90
```typescript { .api }
91
export type Options = {
92
  /**
93
   * Whether ANSI escape codes should be counted. They are ignored by default.
94
   * @default false
95
   */
96
  readonly countAnsiEscapeCodes?: boolean;
97
};
98
```
99

100
## Implementation Details
101

102
- Uses `Intl.Segmenter()` for Unicode-aware string segmentation
103
- Depends on `strip-ansi` package for ANSI escape code removal
104
- Requires Node.js 16+ for `Intl.Segmenter` support
105
- Returns 0 for empty strings (both before and after ANSI stripping)
106
- Iterates through string segments using for...of loop to count visual characters
107

108
## Error Handling
109

110
The function handles edge cases gracefully:
111
- Empty strings return 0
112
- Strings containing only ANSI escape codes return 0 (when `countAnsiEscapeCodes` is false)
113
- Invalid Unicode sequences are handled by the native `Intl.Segmenter` implementation