# CSVJetty for Vue 3

CSV upload, column mapping, validation, and inline correction inside your app. Receive records in a browser callback or deliver them to a configured webhook.

[Try the demo](https://www.csvjetty.com/demo) · [Watch the importer](https://www.csvjetty.com/ImporterDemo.mp4) · [Configure an importer](https://www.csvjetty.com/dashboard)

## Install

```sh
npm install @csvjetty/vue
```

Requires Vue 3.3 or later. Vue 2 is not supported.

## Quick start

Create an importer in the dashboard and copy its public importer key. This example displays received records in memory; it does not save them to a database.

```vue
<script setup>
import { ref } from "vue";
import CSVJetty from "@csvjetty/vue";

const rows = ref([]);
function receiveData(payload) {
  rows.value = payload.rows;
}
</script>

<template>
  <CSVJetty importer-key="YOUR_PUBLIC_IMPORTER_KEY" :on-data="receiveData">
    Import contacts
  </CSVJetty>
  <pre>{{ rows }}</pre>
</template>
```

Use `demo` instead of `importer-key` to try the built-in contacts importer without an account.

## API

| Prop | Purpose |
| --- | --- |
| `importerKey` | Public importer UUID; required unless `demo` is true |
| `demo` | Open the built-in contacts demo; default false |
| `columns` | Optional field definitions and synchronous validators |
| `onData` | Function prop that receives callback records |
| `autoOpen` | Open once after mounting and hide the default button |
| `accentColor` | Default button color; default `#245a44` |
| `baseUrl` | Service origin; default `https://www.csvjetty.com` |
| `previewToken` | Dashboard preview token; normally omitted |

Pass `:on-data` as a function prop, not `@data`: the SDK needs its return value to confirm delivery. The handler may be asynchronous. Return nothing for success or `{ errors: [{ row: 2, message: "Email already exists" }] }` for individual failures. Throw or reject the promise to report a failed save.

| Event | Payload |
| --- | --- |
| `@complete` | `{ importId, accepted, rejected }` |
| `@close` | Normal close; not component unmount |
| `@error` | Opening/configuration error; save errors appear in the importer |

The default slot supplies button text. For a custom trigger:

```vue
<CSVJetty demo>
  <template #trigger="{ open, isOpen }">
    <button type="button" :disabled="isOpen" @click="open">Import contacts</button>
  </template>
</CSVJetty>
```

A template ref exposes `open()`, `close()`, `isOpen`, and `error`. Closing is blocked while busy and asks before discarding unsaved changes. Unmounting removes the importer without cancelling a save already running in your app. Configuration changes apply on the next opening; handlers use current prop values.

### Save records

Replace the example handler with your authenticated API call. Validate records on the server and use `importId` and `rowNumbers` to make repeated deliveries safe. For webhook delivery, configure an HTTPS endpoint in the dashboard and omit `onData`.

With callback delivery, CSV row data stays in the browser until your app handles it; CSVJetty receives configuration and import metadata. Webhook delivery sends records through CSVJetty for delivery and retries. Original uploaded files are not stored by CSVJetty.

### Server rendering

The component does not open the importer during server rendering. `autoOpen` runs after client mounting. In Nuxt, import and use the component in your application as you would another Vue component; use a client-only boundary if your app requires one.

## Documentation

- [Columns and custom validation](https://www.csvjetty.com/docs/columns)
- [Callback payloads and row errors](https://www.csvjetty.com/docs/callbacks)
- [Signed webhooks](https://www.csvjetty.com/docs/webhooks)
- [Requirements and limits](https://www.csvjetty.com/docs/reference/limits)

## Other integrations

| Framework | Package |
| --- | --- |
| React / Next.js | `csvjetty` |
| JavaScript / HTML | `@csvjetty/js` |
| Vue 3 | `@csvjetty/vue` |
| Angular | `@csvjetty/angular` |

## License

MIT. See [LICENSE](./LICENSE). The SDK license does not cover the hosted CSVJetty service.