# CSVJetty documentation

> CSVJetty is a React CSV importer for file upload, automatic column mapping, validation, inline correction, and callback or webhook delivery.

Canonical HTML: https://www.csvjetty.com/docs

## Install

```bash
npm install csvjetty
```

Create an importer in the CSVJetty dashboard and copy its public importer key. The key identifies the saved column configuration and delivery settings for that importer.

## Quick start

```jsx
"use client";

import CSVJetty from "csvjetty";

export default function ImportContacts() {
  return (
    <CSVJetty
      importerKey="YOUR_IMPORTER_KEY"
      onData={async ({ rows }) => {
        console.log(rows);
      }}
    >
      Import contacts
    </CSVJetty>
  );
}
```

Clicking the button opens CSVJetty inside the application. With callback delivery, parsed and validated row data is passed to `onData`.

## How it works

1. The user selects a CSV file.
2. CSVJetty suggests matches between uploaded headers and configured destination fields.
3. Required values and configured data types are validated.
4. The user can correct invalid values before importing.
5. CSVJetty delivers resulting records by callback or webhook.
6. Your application performs final server-side validation and persistence.

CSVJetty does not store the original uploaded CSV file. With callback delivery, imported row data can stay in the browser until your application handles it. Webhook delivery may temporarily retain payloads for reliable delivery and retries.

## Delivery modes

- **Callback delivery:** imported rows are handed to your React application's `onData` handler. A common production pattern is to forward them to an authenticated API you control.
- **Webhook delivery:** CSVJetty sends records server-to-server to a configured HTTPS endpoint using signed requests, retries, and idempotency keys.

See [Delivery modes](https://www.csvjetty.com/docs/concepts/delivery-modes) for the architectural tradeoff.

## Core concepts

- [How CSVJetty works](https://www.csvjetty.com/docs/concepts/how-it-works)
- [Importers](https://www.csvjetty.com/docs/concepts/importers)
- [Column mapping](https://www.csvjetty.com/docs/concepts/column-mapping)
- [Validation and corrections](https://www.csvjetty.com/docs/concepts/validation)
- [Delivery modes](https://www.csvjetty.com/docs/concepts/delivery-modes)

## Next steps

- [React](https://www.csvjetty.com/docs/react)
- [Next.js](https://www.csvjetty.com/docs/nextjs)
- [Configure columns](https://www.csvjetty.com/docs/columns)
- [Reference](https://www.csvjetty.com/docs/reference)

## Watch the workflow

[Watch the importer preview](https://www.csvjetty.com/ImporterDemo.mp4)

Dashboard preview only: no rows are delivered to your application.

[Choose an importer](https://www.csvjetty.com/guides/choose-csv-importer.md)

[Troubleshoot an integration](https://www.csvjetty.com/guides/csv-import-troubleshooting.md)