react-importer v0.2.0

react-importer

A modern CSV importer written in Preact

Contents

• Why?
• Demo
• Installation
• Usage
• Documentation

Why?

Every single project I've worked on needed some hacked together CSV importer. React Importer tries to fix this by implementing a modern CSV import flow for React projects!

Demo

Visit here to see what React Importer looks like in action!

Installation

npm install --save react-importer

React and Vite

• Since this project uses Preact, it is necesary to add the following code to your vite.config.ts to ensure compatibility if your project relies on React
• Detailed documenation on aliasing React to Preact can be found here

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      react: 'preact/compat',
      'react-dom': 'preact/compat',
    },
  },
});

Usage

import Importer from 'react-importer/peer';
import 'react-importer/peer/index.css';

<Importer
  sheets={[
    {
      id: 'employees',
      label: 'Employees',
      columns: [
        {
          label: 'Name',
          id: 'name',
          type: 'string',
          validators: [{ validate: 'required' }],
        },
        {
          label: 'Email',
          id: 'email',
          type: 'string',
          validators: [
            { validate: 'required' },
            { validate: 'unique', error: 'This email is not unique' },
            {
              validate: 'regex_matches',
              regex:
                /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/,
              error: 'This email is not valid',
            },
          ],
        },
        {
          label: 'Phone Number',
          id: 'phone_number',
          type: 'string',
          validators: [{ validate: 'required' }],
        },
        { label: 'City', id: 'city', type: 'string' },
        {
          label: 'State',
          id: 'state',
          type: 'string',
          isReadOnly: true,
          transformers: [{ transformer: 'state_code' }],
        },
      ],
    },
    {
      id: 'companies',
      label: 'Companies',
      columns: [
        {
          label: 'Company',
          id: 'company',
          type: 'string',
          validators: [{ validate: 'required' }],
        },
        {
          label: 'Industry',
          id: 'industry',
          type: 'enum',
          typeArguments: {
            values: [
              { label: 'Tech', value: 'tech' },
              { label: 'Finance', value: 'finance' },
            ],
          },
          validators: [{ validate: 'required' }],
        },
        {
          label: 'Name',
          id: 'name',
          type: 'reference',
          typeArguments: {
            sheetId: 'employees',
            sheetColumnId: 'name',
          },
          validators: [{ validate: 'required' }],
        },
      ],
    },
  ]}
  onComplete={(data) => {
    console.log(data);
  }}
/>;

Documentation

Props

SheetDefinition Props

Column Types

Common Column Props

All column types share these base properties:

• id: string - Unique identifier for the column
• type: ColumnType - Type of the column (described above)
• label: string - Display name for the column
• suggestedMappingKeywords?: string[] - Keywords to help with automatic column mapping
• isReadOnly?: boolean - Whether the column can be edited
• validators?: ImporterValidatorDefinition[] - Array of validation rules
• transformers?: ImporterTransformerDefinition[] - Array of data transformation rules

ImporterState

Example:

{
  sheetDefinitions: [...],
  currentSheetId: "employees",
  mode: "preview",
  validationErrors: [],
  sheetData: [...],
  columnMappings: [
    { csvColumnName: "Name", sheetId: "employees", sheetColumnId: "name" }
  ],
  importProgress: 0
}

SheetState Props

Validators

Transformers

ImporterValidationError

Example:

{
  sheetId: "employees",
  rowIndex: 2,
  columnId: "email",
  message: "Invalid email format"
}

Peer vs Bundled

This package ships with 2 versions you can use:

• /peer - this version is meant to be used with React/Preact - it defines preact as peer dependency
• /bundled - this version is meant to be used without React/Preact - it ships with preact bundled. The user should then use renderImporter function, exported as named export

Customization

Height and Width

You can customize the dimensions by setting height, max-height, width, or max-width. To ensure proper scaling and responsiveness, it's important to include flex.

<div style={{ display: 'flex', height: '80vh' }}>
  <Importer .../>
</div>

Theme Styles

You can further customize theme styles by overriding the following CSS variables in your index.css file:

:root {
  --csv-importer-color-primary: #007bff;
  --csv-importer-color-primary-light: #66b3ff;
  --csv-importer-color-primary-extra-light: #cce7ff;
  --csv-importer-color-secondary: #6c757d;
  --csv-importer-color-tertiary: #17a2b8;
  --csv-importer-color-tertiary-light: #5bc0de;
  --csv-importer-color-success: #28a745;
  --csv-importer-color-danger: #dc3545;
  --csv-importer-color-danger-light: #f5c6cb;
  --csv-importer-color-danger-extra-light: #f8d7da;
  --csv-importer-color-warning: #ffc107;
  --csv-importer-color-info: #17a2b8;
}

These variables allow you to adjust the color scheme for primary, secondary, and tertiary elements, as well as status indicators such as success, danger, warning, and info.

License

MIT © czhu12

Development setup

• Run npm i && npm run watch - this watches for changes in main plugin and rebuilds if needed
• Run cd example && npm i && npm run dev - this runs example application

To run no build example you could run

• npx http-server .