How to Read a Local CSV File Line by Line in JavaScript: Step-by-Step Guide to Extract Data

Table of Contents#

Understanding CSV Files & Line-by-Line Reading
Prerequisites
Method 1: Read Small CSV Files (Load Entire File, Then Split Lines)
- 3.1 Set Up the HTML Structure
- 3.2 Access the Local CSV File
- 3.3 Read the File with FileReader
- 3.4 Split Text into Lines & Process Data
Method 2: Stream Large CSV Files (Read Line-by-Line Without Loading Entire File)
Handling Encodings & Edge Cases
- 5.1 Specifying File Encoding
- 5.2 Dealing with Quoted Fields & Special Characters
Error Handling
Complete Example: Small vs. Large Files
Troubleshooting Common Issues
References

1. Understanding CSV Files & Line-by-Line Reading#

A CSV file stores tabular data as plain text, with rows separated by line breaks and columns separated by delimiters (usually commas, but sometimes tabs or semicolons). For example:

name,email,age  
Alice,[email protected],30  
Bob,[email protected],25

Line-by-line reading processes one row at a time, avoiding loading the entire file into memory. This is essential for:

Large files (e.g., 100k+ rows) to prevent browser crashes.
Real-time validation (e.g., checking for invalid email formats as rows are read).
Memory-constrained environments (e.g., mobile browsers).

2. Prerequisites#

To follow along, you’ll need:

Basic knowledge of HTML and JavaScript.
A modern browser (Chrome 71+, Firefox 65+, Edge 79+ for streaming support).
A sample CSV file (e.g., data.csv with the content above).

3. Method 1: Read Small CSV Files (Load Entire File, Then Split Lines)#

For small CSV files (<10MB), the simplest approach is to load the entire file into memory, convert it to text, and split it into lines. We’ll use the browser’s File API and FileReader for this.

3.1 Set Up the HTML Structure#

First, create a simple UI to let users upload a CSV file and display results:

<!DOCTYPE html>  
<html>  
<body>  
  <h1>Read CSV Line by Line (Small Files)</h1>  
  <input type="file" id="csvFile" accept=".csv" />  
  <pre id="output"></pre>  
 
  <script>  
    // JavaScript code will go here  
  </script>  
</body>  
</html>

input[type="file"]: Lets users select a local CSV file.
accept=".csv": Restricts selection to CSV files.
pre#output: Displays processed data.

3.2 Access the Local CSV File#

Add an event listener to the file input to detect when a user selects a file:

const csvFileInput = document.getElementById('csvFile');  
const output = document.getElementById('output');  
 
csvFileInput.addEventListener('change', handleFileSelect);  
 
function handleFileSelect(event) {  
  const file = event.target.files[0]; // Get the selected file  
  if (!file) {  
    output.textContent = "No file selected.";  
    return;  
  }  
  readSmallCsvFile(file); // Process the file  
}

3.3 Read the File with `FileReader`#

The FileReader API reads file content asynchronously. Use readAsText() to convert the file to a string:

function readSmallCsvFile(file) {  
  const reader = new FileReader();  
 
  // Called when file reading completes  
  reader.onload = function(event) {  
    const csvText = event.target.result; // Raw CSV text  
    processCsvLines(csvText); // Split into lines and process  
  };  
 
  // Read the file as text (default encoding: UTF-8)  
  reader.readAsText(file);  
}

3.4 Split Text into Lines & Process Data#

Split the raw CSV text into lines using split('\n'), then process each line (e.g., split columns, validate data):

function processCsvLines(csvText) {  
  const lines = csvText.split('\n'); // Split by newline character  
  const results = [];  
 
  // Skip empty lines and process rows  
  for (const line of lines) {  
    if (line.trim() === '') continue; // Ignore blank lines  
    const columns = line.split(','); // Split line into columns  
    results.push(columns); // Store as array of arrays  
  }  
 
  // Display results (e.g., as JSON)  
  output.textContent = JSON.stringify(results, null, 2);  
}

Output:

[  
  ["name", "email", "age"],  
  ["Alice", "[email protected]", "30"],  
  ["Bob", "[email protected]", "25"]  
]

4. Method 2: Stream Large CSV Files (Read Line-by-Line Without Loading Entire File)#

For large files (e.g., 1GB CSV), loading the entire file into memory will crash the browser. Instead, use streams to read data in chunks and process lines incrementally.

4.1 Use `ReadableStream` for Streaming#

Modern browsers (Chrome 71+, Firefox 65+) let you stream files using ReadableStream. This API splits the file into small byte chunks, avoiding full memory load:

async function readLargeCsvFile(file) {  
  const stream = file.stream(); // Get readable stream from file  
  // Process the stream...  
}

4.2 Decode Bytes to Text & Split Lines#

Streams return raw bytes, so we need to:

Decode bytes to text using TextDecoderStream.
Split text into lines using a custom transform stream.

Add this to readLargeCsvFile:

async function readLargeCsvFile(file) {  
  const stream = file.stream();  
  const decoder = new TextDecoderStream('utf-8'); // Decode bytes to UTF-8 text  
  const lineSplitter = new TransformStream({  
    transform(chunk, controller) {  
      // Split chunk into lines (handle partial lines across chunks)  
      const lines = chunk.split('\n');  
      lines.forEach((line, index) => {  
        if (index < lines.length - 1) {  
          controller.enqueue(line); // Full line  
        } else {  
          // Partial line (save for next chunk)  
          this.partialLine = (this.partialLine || '') + line;  
        }  
      });  
    },  
    flush(controller) {  
      if (this.partialLine) controller.enqueue(this.partialLine); // Enqueue remaining partial line  
    }  
  });  
 
  // Pipe the stream through decoder and line splitter  
  const processedStream = stream.pipeThrough(decoder).pipeThrough(lineSplitter);  
  processStreamLines(processedStream); // Process lines  
}

4.3 Process Lines Asynchronously#

Use async iterators to loop through the stream line by line:

async function processStreamLines(stream) {  
  const reader = stream.getReader();  
  let result;  
 
  while (!(result = await reader.read()).done) {  
    const line = result.value;  
    if (line.trim() === '') continue; // Skip empty lines  
    const columns = line.split(','); // Split into columns  
    output.textContent += `Line: ${JSON.stringify(columns)}\n`; // Display line  
  }  
 
  output.textContent += "\nStream processing complete!";  
}

Update handleFileSelect to use readLargeCsvFile for large files (e.g., >10MB):

function handleFileSelect(event) {  
  const file = event.target.files[0];  
  if (!file) return;  
 
  // Use streaming for files >10MB  
  if (file.size > 10 * 1024 * 1024) { // 10MB  
    readLargeCsvFile(file);  
  } else {  
    readSmallCsvFile(file); // Use simple method for small files  
  }  
}

5. Handling Encodings & Edge Cases#

5.1 Specifying File Encoding#

CSV files may use encodings like ISO-8859-1 (Western European) or Windows-1252 instead of UTF-8. Specify the encoding in readAsText() or TextDecoderStream:

For small files:

reader.readAsText(file, 'ISO-8859-1'); // Read with ISO-8859-1 encoding

For streaming:

const decoder = new TextDecoderStream('ISO-8859-1'); // Decode with ISO-8859-1

5.2 Dealing with Quoted Fields & Special Characters#

The naive split(',') fails for CSVs with quoted fields containing commas (e.g., "Doe, John",[email protected]). For complex CSVs, use a library like Papa Parse (supports streaming and quoted fields).

Example with Papa Parse:

// Install: npm install papaparse or include via CDN  
Papa.parse(file, {  
  step: function(row) { // Process row-by-row  
    console.log("Row:", row.data);  
  },  
  complete: function() {  
    console.log("Parsing complete!");  
  }  
});

6. Error Handling#

Add error handling to catch issues like invalid files, read failures, or encoding errors:

For FileReader:

reader.onerror = function() {  
  output.textContent = `Error reading file: ${reader.error.message}`;  
};