Vue.js component to handle CSV uploads with field mapping.
This version is for Vue 3. Click here for Vue 2.
VueCsvImport is completely un-styled and customizable. All markup can be replaced and all text can be customized.
Installation
You can install the package via npm or yarn:
# npm
npm install vue-csv-import
# Yarn
yarn add vue-csv-import
You can import components individually.
import {VueCsvToggleHeaders, VueCsvSubmit, VueCsvMap, VueCsvInput, VueCsvErrors, VueCsvImport} from 'vue-csv-import';
Or import all as a plugin.
import {createApp} from "vue";
import App from "./App.vue";
import {VueCsvImportPlugin} from "vue-csv-import";
createApp(App)
.use(VueCsvImportPlugin)
.mount("#app");
A minimal working example with all components will look something like this:
<template>
<vue-csv-import
v-model="csv"
:fields="{name: {required: false, label: 'Name'}, age: {required: true, label: 'Age'}}"
>
<vue-csv-toggle-headers></vue-csv-toggle-headers>
<vue-csv-errors></vue-csv-errors>
<vue-csv-input></vue-csv-input>
<vue-csv-map></vue-csv-map>
</vue-csv-import>
</template>
Components
- VueCsvImport - The primary component wrapper. All other components should be used within this component.
- VueCsvToggleHeaders - Toggles whether CSV should be read as having headers or not.
- VueCsvInput - The file input field to upload your CSV
- VueCsvMap - Used to map CSV columns to your fields
- VueCsvSubmit - Used to POST the mapped CSV.
- VueCsvErrors - Used to display errors.
VueCsvImport
Primary wrapper component.
<template>
<vue-csv-import
v-model="csv"
:fields="{
name: {
required: false,
label: 'Name'
},
age: {
required: true,
label: 'Age'
}
}"
>
<!-- Other Components -->
</vue-csv-import>
</template>
Props:
Prop | Default | Description |
---|---|---|
fields | null | (required) The field names used to map the CSV. |
text | see below | (optional) Override the default text used in the component. |
modelValue | N/A | (optional) Binds to the mapped CSV object. |
Default text
{
errors: {
fileRequired: 'A file is required',
invalidMimeType: "Invalid file type"
},
toggleHeaders: 'File has headers',
submitBtn: 'Submit',
fieldColumn: 'Field',
csvColumn: 'Column'
}
Slot Props:
Prop | Description |
---|---|
file | The selected file |
errors | Current errors |
fields | The fields object |
VueCsvToggleHeaders
Allows user to toggle whether the CSV has headers or not.
<template>
<vue-csv-import>
...
<vue-csv-toggle-headers></vue-csv-toggle-headers>
...
</vue-csv-import>
</template>
Or with custom markup:
<template>
<vue-csv-import>
...
<vue-csv-toggle-headers v-slot="{hasHeaders, toggle}">
<button @click.prevent="toggle">Has Headers</button>
</vue-csv-toggle-headers>
...
</vue-csv-import>
</template>
Props:
Prop | Default | Description |
---|---|---|
checkboxAttributes | {} | (optional) Attributes to bind to the checkbox. |
labelAttributes | {} | (optional) Attributes to bind to the label. |
Slot Props:
Prop | Description |
---|---|
hasHeaders | Whether CSV is marked as having headers. |
toggle | Toggle the 'hasHeaders' value. |
VueCsvInput
The file field for importing CSV.
<template>
<vue-csv-import>
...
<vue-csv-input name="file"></vue-csv-input>
...
</vue-csv-import>
</template>
Or with custom markup:
<template>
<vue-csv-import>
...
<vue-csv-input v-slot="{file, change}">
...
</vue-csv-input>
...
</vue-csv-import>
</template>
Props:
Prop | Default | Description |
---|---|---|
name | N/A | (required) The field names used to map the CSV. |
headers | true | (optional) Override the default text used in the component. |
parseConfig | N/A | (optional) Papaparse config object. |
validation | true | (optional) Use validation or not |
fileMimeTypes | ["text/csv", "text/x-csv", "application/vnd.ms-excel", "text/plain"] | (optional) Accepted CSV file mime types. |
Slot Props:
Prop | Description |
---|---|
file | The current file object |
change | Change the file |
VueCsvMap
Component to map the CSV to the specified fields.
<template>
<vue-csv-import>
...
<vue-csv-map></vue-csv-map>
...
</vue-csv-import>
</template>
Or use slot for custom markup:
<template>
<vue-csv-import>
...
<vue-csv-map v-slot="{sample, map, fields}">
...
</vue-csv-map>
...
</vue-csv-import>
</template>
Props:
Prop | Default | Description |
---|---|---|
noThead | false | (optional) Attributes to bind to the checkbox. |
selectAttributes | {} | (optional) Attributes to bind to the select fields. |
autoMatch | true | (optional) Auto-match fields to columns when they share the same name |
autoMatchIgnoreCase | true | (optional) Ignore case when auto-matching |
Slot Props:
Prop | Description |
---|---|
sample | The first row of the CSV. |
map | The currently mapped fields. |
fields | The fields. |
VueCsvSubmit
Displays a button to post the CSV to specified URL.
<template>
<vue-csv-import>
...
<vue-csv-submit url="/post/here" :config="{}"></vue-csv-submit>
...
</vue-csv-import>
</template>
Or use slot for custom markup:
<template>
<vue-csv-import>
<vue-csv-submit v-slot="{submit, mappedCsv}">
<button @click.prevent="submit">Submit!!</button>
</vue-csv-submit>
</vue-csv-import>
</template>
Props:
Prop | Default | Description |
---|---|---|
url | N/A | (required) Where to post the CSV. |
config | {} | (optional) Axios config object. |
Slot Props:
Prop | Description |
---|---|
submit | Submit the CSV (POST) |
mappedCsv | The mapped CSV object |
VueCsvErrors
Displays any error messages.
<template>
<vue-csv-import>
...
<vue-csv-errors></vue-csv-errors>
...
</vue-csv-import>
</template>
Or use slot for custom markup:
<template>
<vue-csv-import>
...
<vue-csv-errors v-slot="{errors}">
...
</vue-csv-errors>
...
</vue-csv-import>
</template>
Slot Props:
Prop | Description |
---|---|
errors | Object containing errors |
Testing
npm run test
Changelog
Please see CHANGELOG for more information what has changed recently.
Security
If you discover any security related issues, please contact John Gile.
License
The MIT License (MIT). Please see License File for more information.