Browser API Documentation

Client-side CSV parsing for web browsers. Supports parsing CSV strings and file/blob objects with both synchronous and asynchronous methods.

Basic Usage
Parsing CSV Strings
Parsing Files and Blobs
Streaming Large Files
Configuration Options
File Upload Examples
TypeScript Support

Basic Usage

The browser API is accessed through the browser property:

const convert = require('convert-csv-to-json');

// Synchronous parse
const data = convert.browser.csvStringToJson('name,age\nAlice,30');

// Asynchronous parse (recommended)
const dataAsync = await convert.browser.csvStringToJsonAsync('name,age\nAlice,30');

// Parse file
const file = document.querySelector('input[type=file]').files[0];
const fileData = await convert.browser.parseFile(file);

Parsing CSV Strings

Synchronous String Parsing

const convert = require('convert-csv-to-json');

const csv = `name,email,age
John,john@example.com,30
Jane,jane@example.com,25`;

const json = convert.browser.csvStringToJson(csv);
// Output: [
//   { name: 'John', email: 'john@example.com', age: '30' },
//   { name: 'Jane', email: 'jane@example.com', age: '25' }
// ]

Asynchronous String Parsing

async function parseCSV(csv) {
  try {
    const json = await convert.browser.csvStringToJsonAsync(csv);
    console.log(json);
  } catch (error) {
    console.error('Parse error:', error);
  }
}

parseCSV('name,age\nAlice,30\nBob,25');

Get JSON String

const convert = require('convert-csv-to-json');

const csv = 'name,age\nAlice,30';
const jsonString = convert.browser.csvStringToJsonStringified(csv);
// Output: "[\n {\n  \"name\": \"Alice\",\n  \"age\": \"30\"\n }\n]"

Parsing Files and Blobs

Parse File Upload

const convert = require('convert-csv-to-json');

async function handleFileUpload(event) {
  const file = event.target.files[0];
  
  try {
    const json = await convert.browser.parseFile(file);
    console.log('Parsed records:', json.length);
    displayData(json);
  } catch (error) {
    console.error('Error parsing file:', error);
  }
}

// HTML: <input type="file" id="csvFile" accept=".csv">
document.getElementById('csvFile').addEventListener('change', handleFileUpload);

Parse Blob Data

async function parseBlobData(blob) {
  const json = await convert.browser.parseFile(blob);
  return json;
}

// Example: from fetch response
const response = await fetch('data.csv');
const blob = await response.blob();
const data = await parseBlobData(blob);

Parse with Custom Encoding

const convert = require('convert-csv-to-json');

async function parseWithEncoding(file) {
  const options = { encoding: 'utf-8' };
  const json = await convert.browser
    .parseFile(file, options);
  
  return json;
}

Streaming Large Files

For memory-efficient processing of large CSV files in browsers, use the streaming API which processes data in chunks without loading the entire file into memory.

Stream from ReadableStream

const convert = require('convert-csv-to-json');

async function processStream(stream) {
  const jsonData = await convert.browser
    .fieldDelimiter(';')
    .supportQuotedField(true)
    .getJsonFromStreamAsync(stream);
    
  console.log(`Processed ${jsonData.length} records`);
  return jsonData;
}

// Usage with fetch
const response = await fetch('large-dataset.csv');
const stream = response.body;
const data = await processStream(stream);

Stream from File Object

const convert = require('convert-csv-to-json');

async function processLargeFile(file) {
  const jsonData = await convert.browser
    .fieldDelimiter(',')
    .formatValueByType()
    .getJsonFromFileStreamingAsync(file);
    
  console.log(`Streamed and processed ${jsonData.length} records`);
  return jsonData;
}

// Usage with file input
const fileInput = document.querySelector('#csvfile');
fileInput.addEventListener('change', async (event) => {
  const file = event.target.files[0];
  const data = await processLargeFile(file);
  console.log(data);
});

Note: Streaming requires modern browsers that support the ReadableStream API (Chrome 43+, Firefox 65+, Safari 10.1+). For older browsers, the method falls back to regular file parsing.

Configuration Options

All configuration methods from the Sync API are available:

Field Delimiter

const convert = require('convert-csv-to-json');

const csv = 'name;age\nAlice;30\nBob;25';
const json = convert.browser
  .fieldDelimiter(';')
  .csvStringToJson(csv);

Quoted Fields Support

const csv = `name,description
"Smith, John","He said ""Hello"""`;

const json = convert.browser
  .supportQuotedField(true)
  .csvStringToJson(csv);
// Output: { name: 'Smith, John', description: 'He said "Hello"' }

Format Values by Type

const csv = 'name,age,active\nAlice,30,true\nBob,25,false';
const json = convert.browser
  .formatValueByType()
  .csvStringToJson(csv);

// Output:
// [
//   { name: 'Alice', age: 30, active: true },
//   { name: 'Bob', age: 25, active: false }
// ]

Trim Header Fields

const csv = ' Name , Age \nAlice,30';
const json = convert.browser
  .trimHeaderFieldWhiteSpace(true)
  .csvStringToJson(csv);

// Output: { Name: 'Alice', Age: '30' } (spaces removed from header)

Method Chaining

const json = convert.browser
  .fieldDelimiter(';')
  .formatValueByType()
  .supportQuotedField(true)
  .trimHeaderFieldWhiteSpace(true)
  .csvStringToJson(csvContent);

File Upload Examples

HTML File Input

<input type="file" id="csvInput" accept=".csv" />
<button onclick="handleUpload()">Parse CSV</button>
<div id="results"></div>

<script>
const convert = require('convert-csv-to-json');

async function handleUpload() {
  const file = document.getElementById('csvInput').files[0];
  
  if (!file) {
    alert('Please select a file');
    return;
  }
  
  try {
    const json = await convert.browser
      .formatValueByType()
      .parseFile(file);
    
    displayResults(json);
  } catch (error) {
    document.getElementById('results').innerHTML = 
      `<p style="color: red;">Error: ${error.message}</p>`;
  }
}

function displayResults(data) {
  const html = `
    <h3>Parsed ${data.length} records:</h3>
    <pre>${JSON.stringify(data, null, 2)}</pre>
  `;
  document.getElementById('results').innerHTML = html;
}
</script>

Drag and Drop Upload

<div id="dropZone" style="border: 2px dashed #ccc; padding: 20px;">
  Drag CSV file here or <input type="file" id="csvFile" accept=".csv" />
</div>

<script>
const convert = require('convert-csv-to-json');
const dropZone = document.getElementById('dropZone');
const fileInput = document.getElementById('csvFile');

// Handle file selection
fileInput.addEventListener('change', (e) => handleFiles(e.target.files));

// Handle drag and drop
dropZone.addEventListener('dragover', (e) => {
  e.preventDefault();
  dropZone.style.backgroundColor = '#f0f0f0';
});

dropZone.addEventListener('dragleave', () => {
  dropZone.style.backgroundColor = 'transparent';
});

dropZone.addEventListener('drop', (e) => {
  e.preventDefault();
  dropZone.style.backgroundColor = 'transparent';
  handleFiles(e.dataTransfer.files);
});

async function handleFiles(files) {
  const file = files[0];
  if (!file || !file.type.includes('csv')) {
    alert('Please select a CSV file');
    return;
  }
  
  try {
    const json = await convert.browser.parseFile(file);
    console.log('Parsed data:', json);
  } catch (error) {
    console.error('Parse error:', error);
  }
}
</script>

Multiple File Upload

const convert = require('convert-csv-to-json');

async function handleMultipleFiles(files) {
  const results = [];
  
  for (const file of files) {
    try {
      const json = await convert.browser
        .formatValueByType()
        .parseFile(file);
      
      results.push({
        fileName: file.name,
        records: json,
        success: true
      });
    } catch (error) {
      results.push({
        fileName: file.name,
        error: error.message,
        success: false
      });
    }
  }
  
  return results;
}

// Usage with file input
document.getElementById('csvFiles').addEventListener('change', async (e) => {
  const results = await handleMultipleFiles(e.target.files);
  console.log(results);
});

TypeScript Support

import { browser } from 'convert-csv-to-json';

interface User {
  name: string;
  email: string;
  age: number;
}

// Parse CSV string
function parseUsers(csv: string): User[] {
  return browser.csvStringToJson(csv) as User[];
}

// Parse file
async function parseUserFile(file: File): Promise<User[]> {
  return browser
    .formatValueByType()
    .parseFile(file) as Promise<User[]>;
}

// Async string parsing
async function parseUsersAsync(csv: string): Promise<User[]> {
  return browser.csvStringToJsonAsync(csv) as Promise<User[]>;
}

// Handle file upload with type safety
async function handleUpload(event: Event): Promise<void> {
  const input = event.target as HTMLInputElement;
  const file = input.files?.[0];
  
  if (!file) return;
  
  try {
    const users = await parseUserFile(file);
    console.log(`Loaded ${users.length} users`);
  } catch (error) {
    console.error('Failed to parse file:', error);
  }
}

Browser Compatibility

The browser API requires:

FileReader API for file parsing
Modern JavaScript (ES2015+) for async/await support

Supported Browsers:

Chrome 42+ (FileReader)
Firefox 38+ (FileReader)
Safari 10+ (FileReader)
Edge 12+ (FileReader)

Common Issues

FileReader Not Available

if (typeof FileReader === 'undefined') {
  console.error('FileReader API is not available in this environment');
}

File Reading Errors

async function safeParseFile(file) {
  try {
    return await convert.browser.parseFile(file);
  } catch (error) {
    if (error.message.includes('FileReader')) {
      console.error('File reading not supported');
    } else {
      console.error('Parse error:', error);
    }
    return null;
  }
}

Large File Handling

For large files, consider:

Processing in chunks
Using Web Workers for non-blocking parsing
Showing progress feedback to users

async function parseWithProgress(file) {
  const fileSize = file.size;
  console.log(`Parsing file: ${file.name} (${fileSize} bytes)`);
  
  const start = Date.now();
  const json = await convert.browser.parseFile(file);
  const duration = Date.now() - start;
  
  console.log(`Completed in ${duration}ms: ${json.length} records`);
  return json;
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Browser API Documentation

Table of Contents

Basic Usage

Parsing CSV Strings

Synchronous String Parsing

Asynchronous String Parsing

Get JSON String

Parsing Files and Blobs

Parse File Upload

Parse Blob Data

Parse with Custom Encoding

Streaming Large Files

Stream from ReadableStream

Stream from File Object

Configuration Options

Field Delimiter

Quoted Fields Support

Format Values by Type

Trim Header Fields

Method Chaining

File Upload Examples

HTML File Input

Drag and Drop Upload

Multiple File Upload

TypeScript Support

Browser Compatibility

Common Issues

FileReader Not Available

File Reading Errors

Large File Handling

See Also

Uh oh!

FilesExpand file tree

BROWSER.md

Latest commit

History

BROWSER.md

File metadata and controls

Browser API Documentation

Table of Contents

Basic Usage

Parsing CSV Strings

Synchronous String Parsing

Asynchronous String Parsing

Get JSON String

Parsing Files and Blobs

Parse File Upload

Parse Blob Data

Parse with Custom Encoding

Streaming Large Files

Stream from ReadableStream

Stream from File Object

Configuration Options

Field Delimiter

Quoted Fields Support

Format Values by Type

Trim Header Fields

Method Chaining

File Upload Examples

HTML File Input

Drag and Drop Upload

Multiple File Upload

TypeScript Support

Browser Compatibility

Common Issues

FileReader Not Available

File Reading Errors

Large File Handling

See Also