How to import CSV Files with React

In this article we are going to explore how we can use importOK to embed an import wizard into a React application. When we are done, we will be able to upload both CSV and Excel files, map the columns, review and fix any validation errors and finally submit the uploaded data to our API.

Setup your fields

For the sake of simplicity, we will be importing a list of Contacts. Our app will be expecting five fields: first name last name email phone and country.

First, we need to install the React component for importOK.

1npm install @importok/javascript
2npm install @importok/react

Then to embed the import wizard, we can add the following into our page.

 1import ImportokWizard from '@importok/react';
 2 
 3function App() {
 4  /**
 5   * Import fields to be mapped
 6   * Check https://importok.io/docs/fields for more details
 7   */
 8  const fields = {
 9    first_name: {
10      label: 'First Name'
11    },
12    last_name: {
13      label: 'Last Name'
14    },
15    email: {
16      label: 'Email'
17    },
18    phone: {
19      label: 'Phone'
20    },
21    country: {
22      label: 'Country'
23    }
24  };
25 
26  return (
27    <div className="App">
28      <ImportokWizard
29        title="importOK Example for React"
30        fields={fields}
31      />
32    </div>
33  );
34}

The above also defines a list of fields which more or less describe our resource schema. Providing only the labels is sufficient and more than enough to get you started. Give it a go! At this stage you should be able to upload a CSV File and map the columns. Sweet eh?

Normalize and Cleanup your data

More often than not, the data provided by your end-users is not in perfect shape. Extra trailing spaces, incorrectly formatted phone numbers, and other frequent irregularities that take time and effort to resolve.

To improve this, we can use transformers to apply common fixes. The transformation happens right after the file is uploaded and before the validation. importOK provides a handfull of built-in transformers but if necessary you can also add your own.

Let's extend our example to trim any spaces, and capitalize both first and last name.

 1import ImportokWizard from '@importok/react';
 2 
 3function App() {
 4  /**
 5   * Import fields to be mapped
 6   * Check https://importok.io/docs/fields for more details
 7   */
 8  const fields = {
 9    first_name: {
10      label: 'First Name',
11      transformers: 'trim|capitalize'
12    },
13    last_name: {
14      label: 'Last Name',
15      transformers: 'trim|capitalize'
16    },
17    email: {
18      label: 'Email',
19      transformers: 'trim'
20    },
21    phone: {
22      label: 'Phone',
23      transformers: 'trim'
24    },
25    country: {
26      label: 'Country',
27      transformers: 'trim'
28    }
29  };
30 
31  return (
32    <div className="App">
33      <ImportokWizard
34        title="importOK Example for React"
35        fields={fields}
36      />
37    </div>
38  );
39}

Validate your data

While transformers can help auto-heal your data, and bring consistency, they don't cover all the cases. What if the email provided is invalid or the last name is blank?

Validators have been designed to address this problem and provide instant feedback to your end-users, so that they can fix these errors. Similar to transformers, there are some build-in validators and you can add your own as well.

Let's improve further our example to make the last name required, and ensure that the email is in the right format.

 1import ImportokWizard from '@importok/react';
 2function App() {
 3  /**
 4   * Import fields to be mapped
 5   * Check https://importok.io/docs/fields for more details
 6   */
 7  const fields = {
 8    first_name: {
 9      label: 'First Name',
10      transformers: 'trim|capitalize'
11    },
12    last_name: {
13      label: 'Last Name',
14      transformers: 'trim|capitalize',
15      validators: 'required'
16    },
17    email: {
18      label: 'Email',
19      transformers: 'trim',
20      validators: 'email'
21    },
22    phone: {
23      label: 'Phone',
24      transformers: 'trim'
25    },
26    country: {
27      label: 'Country',
28      transformers: 'trim',
29      validators: 'in:countries'
30    }
31  };
32 
33  return (
34    <div className="App">
35      <ImportokWizard
36        title="importOK Example for React"
37        fields={fields}
38      />
39    </div>
40  );
41}

Here is how it looks like at this point. Please note that you can filter by error type and that you can adjust your data without leaving the import wizard.

Push data to your API

There are a couple of options available to push the normalized and validated data to your API. You can either choose to send individuals records in parallel or send the full data set.

Let's use the latter option for our example.

 1import ImportokWizard from '@importok/react';
 2 
 3function App() {
 4  /**
 5   * Import fields to be mapped
 6   * Check https://importok.io/docs/fields for more details
 7   */
 8  const fields = {
 9    first_name: {
10      label: 'First Name',
11      transformers: 'trim|capitalize'
12    },
13    last_name: {
14      label: 'Last Name',
15      transformers: 'trim|capitalize',
16      validators: 'required'
17    },
18    email: {
19      label: 'Email',
20      transformers: 'trim',
21      validators: 'email'
22    },
23    phone: {
24      label: 'Phone',
25      transformers: 'trim'
26    },
27    country: {
28      label: 'Country',
29      transformers: 'trim',
30      validators: 'in:countries'
31    }
32  };
33 
34  /**
35   * Push the normalized and validated records to the API
36   * Check https://importok.io/docs/webhooks for more details
37   */
38  const importRecords = async function (records, meta) {
39    return await fetch('https://your-api.com', {
40        method: 'POST',
41        headers: {
42          'Content-Type': 'application/json'
43        },
44        body: JSON.stringify(records)
45      });
46  };
47 
48  return (
49    <div className="App">
50      <ImportokWizard
51        title="importOK Example for React"
52        fields={fields}
53        onImportReady={importRecords}
54      />
55    </div>
56  );
57}

Conclusion

importOK can be used to import data into your application, by embedding a powerful import wizard and leverage your existing API.

As a guideline, first you need to define the fields, so that your end users can map their data. Then you will need to define some transformers to normalize and clear the data to be imported. Next, you will need to define some validation rules so that you users can get instant feedback when something is wrong. Last, but not least, you will need register your webhooks so that you can actually import the data into your backend system.

importOK provides a free plan that you can use to test the import wizard and ensure that everything works as expected with your app.

Note that there are some limitations with the test plan, such as the number of records you can import and there is no option to add custom transformers or validators. You can always upgrade to a paid plan to unlock these features and more.