0
# Wrap ANSI
1

2
Wrap ANSI is a Node.js library that provides intelligent text wrapping for strings containing ANSI escape codes. It preserves terminal styling, colors, and formatting while wrapping text to specified column widths, making it ideal for CLI applications, logging systems, and terminal output formatting.
3

4
## Package Information
5

6
- **Package Name**: wrap-ansi
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript (ES Module)
9
- **Installation**: `npm install wrap-ansi`
10
- **Node.js Version**: >=18
11

12
## Core Imports
13

14
```javascript
15
import wrapAnsi from 'wrap-ansi';
16
```
17

18
For TypeScript:
19

20
```typescript
21
import wrapAnsi, { type Options } from 'wrap-ansi';
22
```
23

24
For CommonJS:
25

26
```javascript
27
const wrapAnsi = require('wrap-ansi');
28
```
29

30
## Basic Usage
31

32
```javascript
33
import chalk from 'chalk';
34
import wrapAnsi from 'wrap-ansi';
35

36
const input = 'The quick brown ' + chalk.red('fox jumped over ') +
37
	'the lazy ' + chalk.green('dog and then ran away with the unicorn.');
38

39
console.log(wrapAnsi(input, 20));
40
// Output: properly wrapped text with preserved ANSI styling
41
```
42

43
## Capabilities
44

45
### Text Wrapping with ANSI Support
46

47
Wraps words to the specified column width while preserving ANSI escape codes for styling, colors, and hyperlinks.
48

49
```typescript { .api }
50
/**
51
 * Wrap words to the specified column width.
52
 * @param string - A string with ANSI escape codes, like one styled by chalk. Newline characters will be normalized to \n.
53
 * @param columns - The number of columns to wrap the text to.
54
 * @param options - Optional configuration object for wrapping behavior.
55
 * @returns String with proper line wrapping and preserved ANSI styling.
56
 */
57
export default function wrapAnsi(string: string, columns: number, options?: Options): string;
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
import wrapAnsi from 'wrap-ansi';
64
import chalk from 'chalk';
65

66
// Basic wrapping
67
const text = 'This is a long line that needs to be wrapped at a specific width.';
68
const wrapped = wrapAnsi(text, 20);
69
console.log(wrapped);
70

71
// Wrapping with ANSI colors
72
const coloredText = chalk.blue('Hello ') + chalk.red('colorful ') + chalk.green('world!');
73
const wrappedColored = wrapAnsi(coloredText, 10);
74
console.log(wrappedColored);
75

76
// Hard wrap mode - breaks long words
77
const longWord = 'supercalifragilisticexpialidocious';
78
const hardWrapped = wrapAnsi(longWord, 10, { hard: true });
79
console.log(hardWrapped);
80

81
// Disable word wrapping - fill columns completely
82
const noWordWrap = wrapAnsi('word1 word2 word3', 8, { wordWrap: false });
83
console.log(noWordWrap);
84

85
// Preserve whitespace
86
const preserveWhitespace = wrapAnsi('  spaced  text  ', 10, { trim: false });
87
console.log(preserveWhitespace);
88
```
89

90
## Options Configuration
91

92
```typescript { .api }
93
interface Options {
94
	/**
95
	 * By default the wrap is soft, meaning long words may extend past the column width. 
96
	 * Setting this to true will make it hard wrap at the column width.
97
	 * @default false
98
	 */
99
	readonly hard?: boolean;
100

101
	/**
102
	 * By default, an attempt is made to split words at spaces, ensuring that they don't extend past the configured columns. 
103
	 * If wordWrap is false, each column will instead be completely filled splitting words as necessary.
104
	 * @default true
105
	 */
106
	readonly wordWrap?: boolean;
107

108
	/**
109
	 * Whitespace on all lines is removed by default. Set this option to false if you don't want to trim.
110
	 * @default true
111
	 */
112
	readonly trim?: boolean;
113
}
114
```
115

116
### Option Details
117

118
**hard**: Controls word breaking behavior
119
- `false` (default): Soft wrap - long words extend past column width
120
- `true`: Hard wrap - long words are broken at column boundaries
121

122
**wordWrap**: Controls space-based word splitting
123
- `true` (default): Attempts to split at spaces, respecting word boundaries
124
- `false`: Fills columns completely, splitting words as necessary
125

126
**trim**: Controls whitespace handling
127
- `true` (default): Removes whitespace from line beginnings and ends
128
- `false`: Preserves all whitespace as-is
129

130
## ANSI Support Features
131

132
- **Color codes**: Preserves foreground and background colors (including 256-color and RGB support)
133
- **Text styling**: Maintains bold, italic, underline, strikethrough formatting
134
- **Hyperlinks**: Handles ANSI hyperlink escape sequences (OSC 8 hyperlinks)
135
- **Complex sequences**: Supports nested and combined ANSI codes with proper state management
136
- **Unicode support**: Correctly measures character width including full-width characters and emoji
137
- **Escape sequence restoration**: Re-applies styling after line breaks to maintain visual continuity
138
- **String normalization**: Automatically converts `\r\n` to `\n` and normalizes Unicode characters
139

140
## Error Handling
141

142
The function handles various edge cases gracefully:
143
- Empty strings return empty strings (unless `trim: false` with whitespace-only input)
144
- Invalid column numbers are handled by the underlying logic
145
- Malformed ANSI sequences are processed without throwing errors
146
- Newline normalization converts `\r\n` to `\n` automatically