React Spreadsheet Mapper

A headless React library for mapping spreadsheet data with TypeScript support.

Features

• 🚀 Headless: Works with any UI library (Material-UI, Ant Design, Tailwind, etc.)
• 📊 Multi-format Support: Excel (.xlsx, .xls) and CSV files
• 🎯 TypeScript: Full TypeScript support with type safety
• ⚡ Performance: Built-in performance monitoring and optimization
• 🔒 Security: File validation and security features
• ♿ Accessibility: ARIA labels and keyboard navigation support
• 🧪 Well Tested: Comprehensive test coverage

Installation

1npm install react-spreadsheet-mapper

Quick Start

1import React from 'react';
2import useSpreadsheetMapper from 'react-spreadsheet-mapper';
3
4function MyComponent() {
5  const options = [
6    { label: 'Name', value: 'name', required: true },
7    { label: 'Email', value: 'email', required: true },
8    { label: 'Phone', value: 'phone' },
9  ];
10
11  const onFinish = (data) => {
12    console.log('Mapped data:', data);
13    // Send to your API
14  };
15
16  const {
17    map,
18    errors,
19    processedFiles,
20    updateOrCreate,
21    save,
22    handleFiles,
23    handleFileFinish,
24  } = useSpreadsheetMapper({ options, onFinish });
25
26  const handleFileChange = (event) => {
27    const files = Array.from(event.target.files || []);
28    handleFiles(files);
29  };
30
31  return (
32    <div>
33      <input type="file" onChange={handleFileChange} accept=".csv,.xlsx,.xls" />
34      
35      {processedFiles.map((file, index) => (
36        <div key={index}>
37          <h3>{file.name}</h3>
38          {options.map((option) => {
39            const mappedField = map.find(item => item.value === option.value);
40            return (
41              <div key={option.value}>
42                <label>{option.label}</label>
43                <select
44                  value={mappedField?.field || ''}
45                  onChange={(e) => updateOrCreate({
46                    field: e.target.value,
47                    value: option.value,
48                  })}
49                >
50                  <option value="">Select column...</option>
51                  {file.columns.map(column => (
52                    <option key={column} value={column}>{column}</option>
53                  ))}
54                </select>
55                <button onClick={() => save(option.value)}>
56                  Save Mapping
57                </button>
58              </div>
59            );
60          })}
61          <button onClick={() => handleFileFinish(file)}>
62            Process File
63          </button>
64        </div>
65      ))}
66    </div>
67  );
68}

Configuration

1const config = {
2  headerRow: 1,           // Row containing headers (1-indexed)
3  omitHeader: false,      // Whether to omit header row from data
4  dataStartRow: 2,        // Row where data starts (1-indexed)
5  sheet: 0,              // Sheet index to process (0-indexed)
6  previewRowCount: 5,    // Number of preview rows to show
7  security: {
8    maxFileSize: 10 * 1024 * 1024, // 10MB max file size
9    allowedExtensions: ['.csv', '.xlsx', '.xls']
10  },
11  performance: {
12    enableMetrics: true,
13    batchSize: 1000
14  },
15  accessibility: {
16    ariaLabels: {
17      fileInput: 'Upload spreadsheet file',
18      mappingSelect: 'Map column to field'
19    }
20  }
21};
22
23const { ... } = useSpreadsheetMapper({ options, onFinish, config });

API Reference

useSpreadsheetMapper(params)

Parameters

• options - Array of mapping options
• onFinish - Callback when mapping is complete
• config - Optional configuration object

Returns

• map - Current field mappings
• errors - Any processing errors
• processedFiles - Array of processed files
• updateOrCreate - Update or create a mapping
• save - Save a specific mapping
• handleFiles - Process uploaded files
• handleFileFinish - Complete processing for a file
• reset - Reset all state

Examples

Check out our examples repository for implementations with:

• Material-UI
• Ant Design
• React Bootstrap
• Tailwind CSS (shadcn/ui)
• Flowbite React
• Mantine
• Minimal setup

TypeScript Support

Full TypeScript support with exported types:

1import { 
2  SpreadsheetConfig, 
3  SpreadsheetData, 
4  MappedField, 
5  MappingOption 
6} from 'react-spreadsheet-mapper';

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines.

Support

• GitHub Issues
• Documentation