CSV Import Angular

Open-source CSV, TSV, and XLS/XLSX file importer for Angular.

Features

• 📁 Multi-format support: CSV, TSV, XLS, and XLSX files
• 🎨 Theming: Light and dark mode support with customizable primary color
• 🌍 i18n: Built-in translations (English, Spanish, French, German) with custom translation support
• 📱 Modal & Inline: Use as a modal or embed directly in your page
• ✅ Column mapping: Smart column matching with suggested mappings
• 🔧 Customizable: Custom styles, templates, and validation

Live Demo

Try the CSV importer in action! The demo application is available on GitHub Pages:

🌐 View Live Demo

Screenshots

An overall view of the importer running in the default white theme, highlighting the modern modal layout and primary actions.

Step 1 — Upload & template selection: Drag a file into the drop zone or browse from disk, then choose or confirm the correct template before moving on.

Step 2 — Column mapping: Quickly map source columns to your template keys. Suggested matches accelerate the process and required fields are clearly flagged.

Step 3 — Review & completion: Inspect the parsed rows, validate errors, and finish the import once everything looks good.

The demo showcases all features including:

• File upload (CSV, TSV, XLS, XLSX)
• Column mapping with smart suggestions
• Row selection and validation
• Light and dark themes
• Multi-language support

The demo is automatically deployed to GitHub Pages on every push to the main branch.

Installation

npm install @solidexpert/csv-importer-angular
# or
yarn add @solidexpert/csv-importer-angular

Quick Start

import { Component } from '@angular/core';
import { CsvImporterComponent, Template, ImportResult } from '@solidexpert/csv-importer-angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CsvImporterComponent],
  template: `
    <button (click)="isOpen = true">Open Importer</button>
    
    <csv-importer
      [isModal]="true"
      [modalIsOpen]="isOpen"
      [darkMode]="true"
      [template]="template"
      (modalClose)="isOpen = false"
      (complete)="onComplete($event)"
    ></csv-importer>
  `
})
export class AppComponent {
  isOpen = false;
  
  template: Template = {
    columns: [
      {
        name: 'First Name',
        key: 'first_name',
        required: true,
        description: 'The first name of the user',
        suggested_mappings: ['first', 'name']
      },
      {
        name: 'Last Name',
        key: 'last_name',
        suggested_mappings: ['last', 'surname']
      },
      {
        name: 'Email',
        key: 'email',
        required: true
      }
    ]
  };

  onComplete(result: ImportResult): void {
    console.log('Import complete:', result);
    // Process your data here
  }
}

API Reference

Inputs

| Input | Type | Default | Description | |-------|------|---------|-------------| | isModal | boolean | true | Display as modal or inline | | modalIsOpen | boolean | true | Control modal visibility | | modalCloseOnOutsideClick | boolean | false | Close modal on backdrop click | | template | Template \| string | - | Column configuration (required) | | darkMode | boolean | false | Enable dark theme | | primaryColor | string | '#7a5ef8' | Primary brand color | | showDownloadTemplateButton | boolean | true | Show template download button | | skipHeaderRowSelection | boolean | false | Skip header row selection step | | language | string | 'en' | UI language (en, es, fr, de) | | customTranslations | object | - | Custom translation strings | | customStyles | object \| string | - | CSS custom properties |

Outputs

| Output | Type | Description | |--------|------|-------------| | complete | ImportResult | Emitted when import completes successfully | | modalClose | void | Emitted when modal close is triggered |

Template Configuration

interface Template {
  columns: TemplateColumn[];
}

interface TemplateColumn {
  name: string;              // Display name
  key: string;               // Unique identifier
  description?: string;      // Help text
  required?: boolean;        // Mark as required
  suggested_mappings?: string[];  // Auto-match column names
  multiple?: boolean;        // Allow multiple columns to map
  combiner?: (values: string[]) => string;  // Custom value combiner
}

Import Result

interface ImportResult {
  num_rows: number;
  num_columns: number;
  error: string | null;
  columns: { key: string; name: string }[];
  rows: {
    index: number;
    values: Record<string, string | number>;
  }[];
}

Custom Translations

const customTranslations = {
  en: {
    'Upload': 'Upload File',
    'Drop your file here': 'Drag and drop your file here'
  },
  fr: {
    'Upload': 'Téléverser un fichier'
  }
};

// In template
<csv-importer
  [customTranslations]="customTranslations"
></csv-importer>

Custom Styling

const customStyles = {
  '--color-primary': '#10b981',
  '--color-primary-hover': '#059669',
  '--border-radius': '8px'
};

// In template
<csv-importer
  [customStyles]="customStyles"
></csv-importer>

Publishing

This package is automatically published to npm when a new version tag is pushed.

Publishing a new version:

1. Update the version in package.json:

   npm version patch  # for bug fixes (1.0.0 -> 1.0.1)
   npm version minor  # for new features (1.0.0 -> 1.1.0)
   npm version major  # for breaking changes (1.0.0 -> 2.0.0)

2. Push the version commit and tag:

   git push && git push --tags

3. The GitHub Actions workflow will automatically:

   • Build the library
   • Publish to npm as @solidexpert/csv-importer-angular
   • Create a GitHub release

Manual publishing:

You can also trigger the workflow manually from the GitHub Actions tab, or publish directly:

npm run build
npm publish

Note: You need to set up NPM_TOKEN secret in your GitHub repository settings for automatic publishing to work.

License

MIT