0
# CSV Generation (Unparsing)
1

2
JSON-to-CSV conversion functionality with customizable formatting, quote handling, and column ordering. Converts JavaScript objects and arrays into properly formatted CSV strings.
3

4
## Capabilities
5

6
### Papa.unparse()
7

8
Main function for converting JSON data to CSV format with extensive formatting options.
9

10
```javascript { .api }
11
/**
12
 * Convert JSON data to CSV format
13
 * @param input - Data to convert: array of objects, array of arrays, or structured object
14
 * @param config - Unparsing configuration options
15
 * @returns CSV string
16
 */
17
Papa.unparse(input: object[] | string[][] | UnparseObject, config?: UnparseConfig): string;
18
```
19

20
**Input Types:**
21
- **Array of Objects**: `[{name: "John", age: 25}, {name: "Jane", age: 30}]`
22
- **Array of Arrays**: `[["name", "age"], ["John", 25], ["Jane", 30]]`
23
- **UnparseObject**: `{fields: ["name", "age"], data: [["John", 25], ["Jane", 30]]}`
24

25
**Usage Examples:**
26

27
```javascript
28
import Papa from 'papaparse';
29

30
// Convert array of objects
31
const users = [
32
  { name: "John", age: 25, city: "NYC" },
33
  { name: "Jane", age: 30, city: "LA" }
34
];
35
const csv1 = Papa.unparse(users);
36
console.log(csv1);
37
// "name,age,city\nJohn,25,NYC\nJane,30,LA"
38

39
// Convert array of arrays
40
const data = [
41
  ["name", "age", "city"],
42
  ["John", 25, "NYC"],
43
  ["Jane", 30, "LA"]
44
];
45
const csv2 = Papa.unparse(data);
46
console.log(csv2);
47
// "name,age,city\nJohn,25,NYC\nJane,30,LA"
48

49
// Convert structured object
50
const structured = {
51
  fields: ["name", "age", "city"],
52
  data: [
53
    ["John", 25, "NYC"],
54
    ["Jane", 30, "LA"]
55
  ]
56
};
57
const csv3 = Papa.unparse(structured);
58
console.log(csv3);
59
// "name,age,city\nJohn,25,NYC\nJane,30,LA"
60
```
61

62
### Quote Handling
63

64
Control when fields are quoted in the output CSV.
65

66
```javascript { .api }
67
interface QuoteConfig {
68
  quotes?: boolean | boolean[] | ((value: any, columnIndex: number) => boolean); // Quote behavior
69
  quoteChar?: string;             // Quote character (default: ")
70
  escapeChar?: string;            // Escape character for quotes
71
}
72
```
73

74
**Usage Examples:**
75

76
```javascript
77
const data = [
78
  { name: "John Doe", description: "A person who likes to say, \"Hello\"", age: 25 }
79
];
80

81
// Quote all fields
82
const csv1 = Papa.unparse(data, { quotes: true });
83
console.log(csv1);
84
// "\"name\",\"description\",\"age\"\n\"John Doe\",\"A person who likes to say, \"\"Hello\"\"\",\"25\""
85

86
// Quote specific columns only
87
const csv2 = Papa.unparse(data, { 
88
  quotes: [true, true, false] // Quote name and description, not age
89
});
90

91
// Dynamic quoting based on content
92
const csv3 = Papa.unparse(data, {
93
  quotes: function(value, columnIndex) {
94
    // Quote if value contains comma or quotes
95
    return typeof value === 'string' && (value.includes(',') || value.includes('"'));
96
  }
97
});
98

99
// Custom quote character
100
const csv4 = Papa.unparse(data, {
101
  quotes: true,
102
  quoteChar: "'"
103
});
104
console.log(csv4);
105
// "'name','description','age'\n'John Doe','A person who likes to say, \"Hello\"','25'"
106
```
107

108
### Delimiter Configuration
109

110
Customize the field separator character.
111

112
```javascript { .api }
113
interface DelimiterConfig {
114
  delimiter?: string;             // Field delimiter character
115
}
116
```
117

118
**Usage Examples:**
119

120
```javascript
121
const data = [
122
  { name: "John", age: 25, city: "NYC" },
123
  { name: "Jane", age: 30, city: "LA" }
124
];
125

126
// Use semicolon delimiter
127
const csv1 = Papa.unparse(data, { delimiter: ';' });
128
console.log(csv1);
129
// "name;age;city\nJohn;25;NYC\nJane;30;LA"
130

131
// Use tab delimiter
132
const csv2 = Papa.unparse(data, { delimiter: '\t' });
133
console.log(csv2);
134
// "name\tage\tcity\nJohn\t25\tNYC\nJane\t30\tLA"
135

136
// Use pipe delimiter
137
const csv3 = Papa.unparse(data, { delimiter: '|' });
138
console.log(csv3);
139
// "name|age|city\nJohn|25|NYC\nJane|30|LA"
140
```
141

142
### Line Break Configuration
143

144
Control the line terminator characters.
145

146
```javascript { .api }
147
interface LineBreakConfig {
148
  newline?: string;               // Line terminator character(s)
149
}
150
```
151

152
**Usage Examples:**
153

154
```javascript
155
const data = [
156
  { name: "John", age: 25 },
157
  { name: "Jane", age: 30 }
158
];
159

160
// Windows line breaks
161
const csv1 = Papa.unparse(data, { newline: '\r\n' });
162
console.log(csv1);
163
// "name,age\r\nJohn,25\r\nJane,30"
164

165
// Unix line breaks (default)
166
const csv2 = Papa.unparse(data, { newline: '\n' });
167
console.log(csv2);
168
// "name,age\nJohn,25\nJane,30"
169

170
// Custom line separator
171
const csv3 = Papa.unparse(data, { newline: '||\n' });
172
console.log(csv3);
173
// "name,age||\nJohn,25||\nJane,30"
174
```
175

176
### Header Control
177

178
Control whether to include header row in output.
179

180
```javascript { .api }
181
interface HeaderConfig {
182
  header?: boolean;               // Include header row
183
}
184
```
185

186
**Usage Examples:**
187

188
```javascript
189
const data = [
190
  { name: "John", age: 25 },
191
  { name: "Jane", age: 30 }
192
];
193

194
// Include headers (default)
195
const csv1 = Papa.unparse(data, { header: true });
196
console.log(csv1);
197
// "name,age\nJohn,25\nJane,30"
198

199
// Exclude headers
200
const csv2 = Papa.unparse(data, { header: false });
201
console.log(csv2);
202
// "John,25\nJane,30"
203

204
// For array of arrays, first row is treated as header
205
const arrayData = [
206
  ["name", "age"],
207
  ["John", 25],
208
  ["Jane", 30]
209
];
210
const csv3 = Papa.unparse(arrayData, { header: false });
211
console.log(csv3);
212
// "name,age\nJohn,25\nJane,30" (first row still included)
213
```
214

215
### Column Ordering
216

217
Specify the order of columns in the output CSV.
218

219
```javascript { .api }
220
interface ColumnConfig {
221
  columns?: string[];             // Column order for object unparsing
222
}
223
```
224

225
**Usage Examples:**
226

227
```javascript
228
const users = [
229
  { age: 25, name: "John", city: "NYC", country: "USA" },
230
  { age: 30, name: "Jane", city: "LA", country: "USA" }
231
];
232

233
// Specify column order
234
const csv1 = Papa.unparse(users, {
235
  columns: ["name", "city", "age"] // Exclude country, reorder columns
236
});
237
console.log(csv1);
238
// "name,city,age\nJohn,NYC,25\nJane,LA,30"
239

240
// Include all columns in specific order
241
const csv2 = Papa.unparse(users, {
242
  columns: ["country", "city", "name", "age"]
243
});
244
console.log(csv2);
245
// "country,city,name,age\nUSA,NYC,John,25\nUSA,LA,Jane,30"
246
```
247

248
### Empty Line Handling
249

250
Control how empty rows are handled in the output.
251

252
```javascript { .api }
253
interface EmptyLineConfig {
254
  skipEmptyLines?: boolean | 'greedy'; // Skip empty lines behavior
255
}
256
```
257

258
**Usage Examples:**
259

260
```javascript
261
const data = [
262
  { name: "John", age: 25 },
263
  { name: "", age: null },  // Empty name, null age
264
  { name: "Jane", age: 30 }
265
];
266

267
// Include empty lines (default)
268
const csv1 = Papa.unparse(data);
269
console.log(csv1);
270
// "name,age\nJohn,25\n,\nJane,30"
271

272
// Skip completely empty lines
273
const csv2 = Papa.unparse(data, { skipEmptyLines: true });
274
console.log(csv2);
275
// "name,age\nJohn,25\n,\nJane,30" (line with empty values still included)
276

277
// Skip lines with only whitespace/empty values
278
const csv3 = Papa.unparse(data, { skipEmptyLines: 'greedy' });
279
console.log(csv3);
280
// "name,age\nJohn,25\nJane,30" (empty value line skipped)
281
```
282

283
### Formula Escaping
284

285
Prevent CSV fields from being interpreted as spreadsheet formulas.
286

287
```javascript { .api }
288
interface FormulaConfig {
289
  escapeFormulae?: boolean;       // Escape potential spreadsheet formulas
290
}
291
```
292

293
**Usage Examples:**
294

295
```javascript
296
const data = [
297
  { name: "John", formula: "=SUM(A1:A10)" },
298
  { name: "Jane", formula: "+1+1" },
299
  { name: "Bob", formula: "-1+2" },
300
  { name: "Alice", formula: "@SUM(1,2)" }
301
];
302

303
// Escape formulas for safety
304
const csv = Papa.unparse(data, { escapeFormulae: true });
305
console.log(csv);
306
// "name,formula\nJohn,'=SUM(A1:A10)\nJane,'+1+1\nBob,'-1+2\nAlice,'@SUM(1,2)"
307
// Formulas are prefixed with single quote to prevent execution
308
```
309

310
### JSON String Input
311

312
Parse JSON strings before converting to CSV.
313

314
```javascript { .api }
315
/**
316
 * Convert JSON string to CSV
317
 * @param input - JSON string representation of data
318
 * @param config - Unparsing configuration
319
 */
320
Papa.unparse(input: string, config?: UnparseConfig): string;
321
```
322

323
**Usage Examples:**
324

325
```javascript
326
// JSON string input
327
const jsonString = '[{"name":"John","age":25},{"name":"Jane","age":30}]';
328
const csv = Papa.unparse(jsonString);
329
console.log(csv);
330
// "name,age\nJohn,25\nJane,30"
331

332
// JSON string with nested data property
333
const nestedJsonString = '{"data":[["name","age"],["John",25],["Jane",30]]}';
334
const csv2 = Papa.unparse(nestedJsonString);
335
console.log(csv2);
336
// "name,age\nJohn,25\nJane,30"
337
```
338

339
### Advanced Configuration
340

341
Complete configuration interface for fine-tuned control.
342

343
```javascript { .api }
344
interface UnparseConfig {
345
  quotes?: boolean | boolean[] | ((value: any, columnIndex: number) => boolean); // Quote behavior
346
  quoteChar?: string;             // Quote character (default: ")
347
  escapeChar?: string;            // Escape character for quotes within quotes
348
  delimiter?: string;             // Field delimiter (default: ,)
349
  header?: boolean;               // Include header row (default: true)
350
  newline?: string;               // Line terminator (default: \r\n)
351
  skipEmptyLines?: boolean | 'greedy'; // Skip empty lines behavior
352
  columns?: string[];             // Column order for object unparsing
353
  escapeFormulae?: boolean;       // Escape spreadsheet formulas (default: false)
354
}
355

356
interface UnparseObject {
357
  fields: string[];               // Column headers
358
  data: any[][];                  // Data rows as arrays
359
}
360
```
361

362
**Complete Example:**
363

364
```javascript
365
const complexData = [
366
  { 
367
    id: 1,
368
    name: "John, Jr.", 
369
    email: "john@example.com",
370
    notes: "Likes to say \"Hello!\"",
371
    formula: "=A1+B1",
372
    active: true
373
  },
374
  { 
375
    id: 2,
376
    name: "Jane Smith", 
377
    email: "jane@example.com",
378
    notes: "",
379
    formula: "+10*2",
380
    active: false
381
  }
382
];
383

384
const csv = Papa.unparse(complexData, {
385
  quotes: function(value, columnIndex) {
386
    // Quote strings that contain special characters
387
    return typeof value === 'string' && 
388
           (value.includes(',') || value.includes('"') || value.includes('\n'));
389
  },
390
  quoteChar: '"',
391
  escapeChar: '"',
392
  delimiter: ',',
393
  header: true,
394
  newline: '\n',
395
  skipEmptyLines: 'greedy',
396
  columns: ['id', 'name', 'email', 'active', 'notes'], // Exclude formula
397
  escapeFormulae: true
398
});
399

400
console.log(csv);
401
// Properly formatted CSV with escaped quotes and controlled quoting
402
```