0
# CSV Parsing
1

2
Core CSV-to-JSON parsing functionality with automatic type conversion, delimiter detection, and comprehensive error handling. Supports multiple input formats and extensive configuration options.
3

4
## Capabilities
5

6
### Papa.parse()
7

8
Main parsing function that converts CSV data to JSON format with extensive configuration options.
9

10
```javascript { .api }
11
/**
12
 * Parse CSV data into JSON format
13
 * @param input - CSV string, File object, or Node.js ReadableStream
14
 * @param config - Parsing configuration options
15
 * @returns Parsed result object or Node.js ReadableStream
16
 */
17
Papa.parse(input: string | File | NodeJS.ReadableStream | 1, config?: ParseConfig): ParseResult | NodeJS.ReadableStream;
18
```
19

20
**Input Types:**
21
- **String**: Direct CSV text data
22
- **File**: Browser File object from `<input type="file">`
23
- **ReadableStream**: Node.js readable stream (Node.js only)
24
- **Papa.NODE_STREAM_INPUT**: Special constant for Node.js duplex streaming
25

26
**Usage Examples:**
27

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

31
// Parse CSV string
32
const csvString = "name,age,email\nJohn,25,john@example.com\nJane,30,jane@example.com";
33
const result = Papa.parse(csvString, {
34
  header: true,
35
  dynamicTyping: true
36
});
37
console.log(result.data);
38
// [{ name: "John", age: 25, email: "john@example.com" }, ...]
39

40
// Parse with custom delimiter
41
const tsvData = "name\tage\temail\nJohn\t25\tjohn@example.com";
42
const tsvResult = Papa.parse(tsvData, {
43
  delimiter: '\t',
44
  header: true
45
});
46

47
// Parse File object (browser)
48
const fileInput = document.getElementById('csvFile');
49
fileInput.addEventListener('change', function(e) {
50
  const file = e.target.files[0];
51
  Papa.parse(file, {
52
    header: true,
53
    complete: function(results) {
54
      console.log(results.data);
55
    }
56
  });
57
});
58
```
59

60
### Header Processing
61

62
Parse CSV files with header rows and transform header names.
63

64
```javascript { .api }
65
interface HeaderConfig {
66
  header?: boolean;                           // Treat first row as headers
67
  transformHeader?: (header: string) => string; // Transform header names
68
}
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
// Basic header parsing
75
const csvWithHeaders = "First Name,Last Name,Age\nJohn,Doe,25";
76
const result = Papa.parse(csvWithHeaders, { header: true });
77
console.log(result.data[0]);
78
// { "First Name": "John", "Last Name": "Doe", Age: "25" }
79

80
// Transform header names
81
const result2 = Papa.parse(csvWithHeaders, {
82
  header: true,
83
  transformHeader: function(header) {
84
    return header.toLowerCase().replace(' ', '_');
85
  }
86
});
87
console.log(result2.data[0]);
88
// { first_name: "John", last_name: "Doe", age: "25" }
89
```
90

91
### Dynamic Typing
92

93
Automatically convert string values to appropriate JavaScript types.
94

95
```javascript { .api }
96
interface DynamicTypingConfig {
97
  dynamicTyping?: boolean | object | ((field: string) => boolean);
98
}
99
```
100

101
**Usage Examples:**
102

103
```javascript
104
const csvData = "name,age,active,score\nJohn,25,true,95.5\nJane,30,false,87.2";
105

106
// Enable for all fields
107
const result1 = Papa.parse(csvData, {
108
  header: true,
109
  dynamicTyping: true
110
});
111
console.log(result1.data[0]);
112
// { name: "John", age: 25, active: true, score: 95.5 }
113

114
// Enable for specific fields only
115
const result2 = Papa.parse(csvData, {
116
  header: true,
117
  dynamicTyping: {
118
    age: true,
119
    score: true
120
  }
121
});
122
console.log(result2.data[0]);
123
// { name: "John", age: 25, active: "true", score: 95.5 }
124

125
// Use function to determine dynamically
126
const result3 = Papa.parse(csvData, {
127
  header: true,
128
  dynamicTyping: function(field) {
129
    return field !== 'name'; // Convert all except name
130
  }
131
});
132
```
133

134
### Data Transformation
135

136
Transform values during parsing with custom functions.
137

138
```javascript { .api }
139
interface TransformConfig {
140
  transform?: (value: string, field: string | number) => any;
141
}
142
```
143

144
**Usage Examples:**
145

146
```javascript
147
const csvData = "name,email,created_date\nJohn,JOHN@EXAMPLE.COM,2023-01-15";
148
const result = Papa.parse(csvData, {
149
  header: true,
150
  transform: function(value, field) {
151
    if (field === 'email') {
152
      return value.toLowerCase();
153
    }
154
    if (field === 'created_date') {
155
      return new Date(value);
156
    }
157
    return value;
158
  }
159
});
160
console.log(result.data[0]);
161
// { name: "John", email: "john@example.com", created_date: Date object }
162
```
163

164
### Error Handling
165

166
Comprehensive error reporting with detailed information about parsing issues.
167

168
```javascript { .api }
169
interface ParseError {
170
  type: string;                    // Error category
171
  code: string;                    // Specific error code
172
  message: string;                 // Human-readable error message
173
  row: number;                     // Row number where error occurred
174
}
175

176
interface ErrorHandlingConfig {
177
  error?: (error: ParseError) => void; // Error callback function
178
}
179
```
180

181
**Usage Examples:**
182

183
```javascript
184
const malformedCsv = 'name,age\nJohn,25\nJane,"30,active';
185
const result = Papa.parse(malformedCsv, {
186
  header: true,
187
  error: function(error) {
188
    console.error('Parse error:', error.message, 'at row', error.row);
189
  }
190
});
191
console.log(result.errors);
192
// Array of error objects with details
193
```
194

195
### Delimiter Detection
196

197
Automatic detection of field delimiters or manual specification.
198

199
```javascript { .api }
200
interface DelimiterConfig {
201
  delimiter?: string;              // Specific delimiter character
202
  delimitersToGuess?: string[];    // Delimiters to try during auto-detection
203
}
204
```
205

206
**Usage Examples:**
207

208
```javascript
209
// Automatic delimiter detection (default)
210
const csvData = "name;age;city\nJohn;25;NYC";
211
const result1 = Papa.parse(csvData, { header: true });
212
// Automatically detects semicolon delimiter
213

214
// Manual delimiter specification
215
const result2 = Papa.parse(csvData, {
216
  delimiter: ';',
217
  header: true
218
});
219

220
// Custom delimiter detection list
221
const result3 = Papa.parse(csvData, {
222
  delimitersToGuess: [';', '|', '\t'],
223
  header: true
224
});
225
```
226

227
### Quote and Escape Handling
228

229
Handle quoted fields and escape characters properly.
230

231
```javascript { .api }
232
interface QuoteConfig {
233
  quoteChar?: string;              // Quote character (default: ")
234
  escapeChar?: string;             // Escape character
235
}
236
```
237

238
**Usage Examples:**
239

240
```javascript
241
// Handle quoted fields with commas
242
const csvData = 'name,description\n"John Doe","A person who likes to say, \\"Hello\\""';
243
const result = Papa.parse(csvData, {
244
  header: true,
245
  quoteChar: '"',
246
  escapeChar: '\\'
247
});
248
console.log(result.data[0]);
249
// { name: "John Doe", description: "A person who likes to say, \"Hello\"" }
250

251
// Custom quote character
252
const csvData2 = "name,description\n'John Doe','A simple description'";
253
const result2 = Papa.parse(csvData2, {
254
  header: true,
255
  quoteChar: "'"
256
});
257
```
258

259
### Line Break Handling
260

261
Handle different line break formats across platforms.
262

263
```javascript { .api }
264
interface LineBreakConfig {
265
  newline?: string;                // Line terminator character(s)
266
}
267
```
268

269
**Usage Examples:**
270

271
```javascript
272
// Handle Windows line breaks
273
const windowsCsv = "name,age\r\nJohn,25\r\nJane,30";
274
const result1 = Papa.parse(windowsCsv, {
275
  newline: '\r\n',
276
  header: true
277
});
278

279
// Handle Unix line breaks
280
const unixCsv = "name,age\nJohn,25\nJane,30";
281
const result2 = Papa.parse(unixCsv, {
282
  newline: '\n',
283
  header: true
284
});
285

286
// Automatic line break detection (default)
287
const result3 = Papa.parse(windowsCsv, { header: true });
288
// Automatically detects \r\n
289
```
290

291
### Preview Mode
292

293
Parse only a limited number of rows for data sampling.
294

295
```javascript { .api }
296
interface PreviewConfig {
297
  preview?: number;                // Maximum number of rows to parse
298
}
299
```
300

301
**Usage Examples:**
302

303
```javascript
304
const largeCsv = "name,age\n" + Array.from({length: 1000}, (_, i) => `Person${i},${20+i}`).join('\n');
305

306
// Parse only first 10 rows
307
const preview = Papa.parse(largeCsv, {
308
  header: true,
309
  preview: 10
310
});
311
console.log(preview.data.length); // 10
312
console.log(preview.meta.truncated); // true
313
```
314

315
### Comments
316

317
Skip lines that start with comment characters.
318

319
```javascript { .api }
320
interface CommentConfig {
321
  comments?: string | boolean;     // Comment character or false to disable
322
}
323
```
324

325
**Usage Examples:**
326

327
```javascript
328
const csvWithComments = `# This is a comment
329
name,age
330
# Another comment
331
John,25
332
Jane,30`;
333

334
const result = Papa.parse(csvWithComments, {
335
  header: true,
336
  comments: '#'
337
});
338
console.log(result.data);
339
// Only data rows, comments are ignored
340
```
341

342
### Fast Mode
343

344
Optimized parsing for well-formed CSV data without extensive error checking.
345

346
```javascript { .api }
347
interface FastModeConfig {
348
  fastMode?: boolean;              // Enable fast parsing mode
349
}
350
```
351

352
**Usage Examples:**
353

354
```javascript
355
const cleanCsv = "name,age,city\nJohn,25,NYC\nJane,30,LA";
356
const result = Papa.parse(cleanCsv, {
357
  header: true,
358
  fastMode: true // Faster parsing, assumes data is well-formed
359
});
360
```
361

362
### Empty Line Handling
363

364
Control how empty lines in CSV data are processed.
365

366
```javascript { .api }
367
interface EmptyLineConfig {
368
  skipEmptyLines?: boolean | 'greedy'; // Skip empty lines behavior
369
}
370
```
371

372
**Usage Examples:**
373

374
```javascript
375
const csvWithEmptyLines = `name,age
376

377
John,25
378

379
Jane,30
380
`;
381

382
// Skip completely empty lines
383
const result1 = Papa.parse(csvWithEmptyLines, {
384
  header: true,
385
  skipEmptyLines: true
386
});
387

388
// Skip lines with only whitespace
389
const result2 = Papa.parse(csvWithEmptyLines, {
390
  header: true,
391
  skipEmptyLines: 'greedy'
392
});
393
```