Vue CSV Processor

A Vue 3 component library for CSV file processing with robust encoding detection, preview, and column mapping.

Features

• 🌐 Multi-Encoding Support: Automatically detect and switch between encodings (UTF-8, ISO-8859-1, Windows-1252, etc.)
• 📊 Live Data Preview: View your data with different encodings before processing
• 🗄️ Column Mapping: Map CSV columns to your data structure with auto-matching
• 📝 Header Row Control: Toggle whether the first row should be treated as headers
• 🧠 Smart Parsing: Handles complex CSV data with embedded commas, quotes, and special characters
• 🚨 Error Handling: Clear error messages for parsing and validation issues
• 🧩 Modular Components: Use all components together or pick just what you need
• 🎨 Custom Styling: All components can be fully styled or replaced with custom markup

Installation

# npm
npm install vue-csv-processor

# Yarn
yarn add vue-csv-processor

Usage

Basic Example

<template>
  <div>
    <h1>CSV Importer</h1>
    
    <VueCsvProcessor 
      v-model="csvData" 
      :fields="fields"
    >
      <VueCsvInput />
      <VueCsvToggleHeaders />
      <VueCsvPreview />
      <VueCsvErrors />
      <VueCsvMap />
      
      <div v-if="csvData.length" class="actions">
        <button @click="processData">Submit Data</button>
      </div>
    </VueCsvProcessor>
    
    <pre v-if="csvData.length">{{ csvData }}</pre>
  </div>
</template>

<script>
import { ref, defineComponent } from 'vue';
import { 
  VueCsvProcessor, 
  VueCsvInput, 
  VueCsvToggleHeaders,
  VueCsvPreview,
  VueCsvMap,
  VueCsvErrors
} from 'vue-csv-processor';

export default defineComponent({
  components: {
    VueCsvProcessor,
    VueCsvInput,
    VueCsvToggleHeaders,
    VueCsvPreview,
    VueCsvMap,
    VueCsvErrors
  },
  
  setup() {
    const csvData = ref([]);
    
    const fields = {
      name: { required: true, label: 'Full Name' },
      email: { required: true, label: 'Email Address' },
      phone: { required: false, label: 'Phone Number' },
      address: { required: false, label: 'Address' }
    };
    
    const processData = () => {
      // Do something with csvData.value
      console.log('Processed data:', csvData.value);
    };
    
    return {
      csvData,
      fields,
      processData
    };
  }
});
</script>

Global Registration

You can register all components globally:

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import { VueCsvProcessorPlugin } from 'vue-csv-processor';

const app = createApp(App);
app.use(VueCsvProcessorPlugin);
app.mount('#app');

Components

VueCsvProcessor

The main wrapper component that provides context and state for all child components.

Props

Prop	Type	Default	Description
modelValue	Array	[]	v-model binding for the processed CSV data
fields	Object	Required	Field definitions to map CSV columns to
text	Object	See below	Custom text overrides
autoMatch	Boolean	true	Auto map CSV columns to fields by name
defaultEncoding	String	'UTF-8'	Default encoding to use

Default Text

{
  errors: {
    fileRequired: 'A file is required',
    invalidMimeType: 'Invalid file type',
    encodingError: 'Error processing file with selected encoding'
  },
  toggleHeaders: 'File has headers',
  submitBtn: 'Submit',
  fieldColumn: 'Field',
  csvColumn: 'Column',
  encoding: 'Text Encoding'
}

Slot Props

Prop	Description
file	The selected file
errors	Current errors
fields	Field definitions
mapping	Current column mapping
hasHeaders	Whether CSV is treated as having headers
csvData	Parsed CSV data
rawContent	Raw CSV content
encoding	Current encoding

VueCsvInput

File input component for selecting CSV files.

Props

Prop	Type	Default	Description
name	String	'csv-file'	Input field name
accept	String	'.csv,text/csv,...'	Accepted file types
validation	Boolean	true	Whether to perform validation
fileMimeTypes	Array	['text/csv', ...]	Allowed file MIME types
maxSize	Number	5242880	Maximum file size (5MB)
disabled	Boolean	false	Whether the input is disabled

Slot Props

Prop	Description
file	The selected file
change	Function to handle file change
remove	Function to remove the file
errors	File errors

VueCsvPreview

Preview component for viewing CSV data with encoding selection.

Props

Prop	Type	Default	Description
encoding	String	'UTF-8'	Selected encoding (v-model:encoding)
encodings	Array	[all supported encodings]	List of encodings to show
rowCount	Number	5	Number of preview rows
showRowNumbers	Boolean	true	Whether to show row numbers
encodingSelectId	String	'csv-encoding-select'	ID for the encoding select

Slot Props

Prop	Description
previewData	Data for preview
parsedHeaders	CSV headers
totalRows	Total number of rows
encoding	Current encoding
supportedEncodings	Available encodings
changeEncoding	Function to change encoding
hasEncodingIssues	Whether encoding issues are detected

VueCsvToggleHeaders

Toggle component for setting whether CSV has headers.

Props

Prop	Type	Default	Description
toggleId	String	'csv-has-headers'	HTML ID for the checkbox
checkboxAttributes	Object	{}	Additional attributes for checkbox
labelAttributes	Object	{}	Additional attributes for label

Slot Props

Prop	Description
hasHeaders	Whether CSV is treated as having headers
toggle	Function to toggle headers

VueCsvMap

Column mapping component for associating CSV columns with data fields.

Props

Prop	Type	Default	Description
noThead	Boolean	false	Hide table header
selectAttributes	Object	{}	Additional attributes for select inputs
autoMatch	Boolean	true	Auto-match fields to columns by name
autoMatchIgnoreCase	Boolean	true	Ignore case when auto-matching

Slot Props

Prop	Description
sample	Sample data for preview
mapping	Current column mapping
fields	Field definitions
parsedHeaders	CSV headers
updateMapping	Function to update mapping

VueCsvErrors

Error display component for showing CSV parsing and validation errors.

Slot Props

Prop	Description
errors	List of errors

Utilities

The package also exports some utility functions:

import { parseCSV, detectEncoding } from 'vue-csv-processor';

// Parse CSV content manually
const result = parseCSV(csvContent, {
  hasHeaders: true,
  delimiter: ',',
  trimFields: true,
  encoding: 'UTF-8'
});

// Detect encoding from file buffer
const detectedEncoding = detectEncoding(fileBuffer);

Styling

All components include basic styling with scoped CSS. You can override these styles or provide completely custom markup using slots.

License

MIT