Web Component

Add a complete CSV and Excel importer to your Next.js app, with column mapping, real-time validation, and API integration built in.

@importok/javascript

Installation

Install the following package

1npm install @importok/javascript

Note: The trial version is available on NPM. When you upgrade, you'll get access to our private packages with full features. No code changes required.

Your first importer

Create a basic contact importer:

 1<script>
 2import ImportOK from './node_modules/@importok/javascript/importok.js';
 3ImportOK.defineCustomElements();
 4 
 5const fields = {
 6  first_name: { label: 'First Name' },
 7  last_name: { label: 'Last Name' },
 8  email: { label: 'Email' },
 9  phone: { label: 'Phone' },
10  country: { label: 'Country' }
11};
12 
13const wizard = document.querySelector('importok-wizard');
14wizard.config = {
15  title: 'Import Contacts',
16  fields: fields
17};
18</script>
19<body>
20  <importok-wizard></importok-wizard>
21</body>

That's it. Users can now upload CSV or Excel files and map columns to your fields.

Make it production-ready

Add data transformations

Clean up data before validation using transformers:

 1const fields = {
 2  first_name: {
 3    label: 'First Name',
 4    transformers: 'trim|capitalize'  // Built-in transformers
 5  },
 6  last_name: {
 7    label: 'Last Name',
 8    transformers: 'trim|capitalize'
 9  },
10  email: {
11    label: 'Email',
12    transformers: 'trim'
13  }
14};

See all built-in transformers →

Add validation rules

Catch errors before they reach your API using validators:

 1const fields = {
 2  first_name: {
 3    label: 'First Name',
 4    transformers: 'trim|capitalize'
 5  },
 6  last_name: {
 7    label: 'Last Name',
 8    transformers: 'trim|capitalize',
 9    validators: 'required'  // Built-in validators
10  },
11  email: {
12    label: 'Email',
13    transformers: 'trim',
14    validators: 'email|required'
15  }
16};

See all built-in validators →

Connect to your API

Send validated data to your backend:

1const saveRecords = async function (records, meta) {
2  const response = await fetch('/api/contacts/imports', {
3    method: 'POST',
4    headers: { 'Content-Type': 'application/json' },
5    body: JSON.stringify(records)
6  });
7 
8  return response;
9};

Complete example

Here's everything together:

 1<script>
 2import ImportOK from './node_modules/@importok/javascript/importok.js';
 3ImportOK.defineCustomElements();
 4 
 5const fields = {
 6  first_name: { label: 'First Name' },
 7  last_name: { label: 'Last Name' },
 8  email: { label: 'Email' },
 9  phone: { label: 'Phone' },
10  country: { label: 'Country' }
11};
12 
13const saveRecords = async function (records, meta) {
14  const response = await fetch('/api/contacts/imports', {
15    method: 'POST',
16    headers: { 'Content-Type': 'application/json' },
17    body: JSON.stringify(records)
18  });
19 
20  return response;
21};
22 
23const wizard = document.querySelector('importok-wizard');
24wizard.config = {
25  title: 'Import Contacts',
26  fields: fields,
27  onImportReady: saveRecords
28};
29</script>
30<body>
31  <importok-wizard></importok-wizard>
32</body>

Next steps

Now that you have a working importer, explore advanced features:

Custom validators - Add business-specific validation rules
Custom transformers - Create domain-specific data cleanup
Data providers - Connect dropdowns to your API
Props & events - Customize behavior and styling
Field configuration - Deep dive into field options

Try it live

Experiment with a complete example in StackBlitz: Open in StackBlitz →

Trial limitations

The free trial includes:

✅ Full UI and mapping features
✅ Built-in validators and transformers
⚠️ 20 records per import (unlimited on paid plans)
⚠️ Up to 2 custom validators (unlimited on paid plans)
⚠️ Up to 2 custom transformers (unlimited on paid plans)
⚠️ Up to 2 data providers (unlimited on paid plans)

When you're ready, upgrade to unlock full features with access to our private packages.

Getting Started

Core Concepts

Guides

Reference