CSV Import

ExportExcelPlugin imports CSV files by default. .xlsx and .xls parsing is app-owned; use a parser such as SheetJS, ExcelJS, or read-excel-file and assign normalized rows to the grid yourself.

Tip

For app-owned XLSX parsing choices, see Excel Import and Export Libraries.

Drag And Drop

By default, users can drop a .csv file onto the grid:

Download sample CSV

Download the sample, then drag it onto the grid to verify the import flow.

Control drag/drop import with grid.exportExcel:

grid.exportExcel = {
  allowDrag: true,
  allowedExtensions: ['.csv'],
};

The same options are still accepted through legacy additionalData.excel, but new code should prefer grid.exportExcel.

export-excel.types.ts

/**
 * The `ExcelConfig` type defines configuration options for handling CSV file imports
 * in RevoGrid, allowing developers to tailor how CSV files are parsed and integrated
 * into the grid environment.
 *
 *  **Features**:
 * - Drag-and-drop support for CSV files, which can be enabled or disabled via `allowDrag`.
 * - CSV import handling with optional column generation from the first row.
 * - Control over column generation with `skipColumnGeneration`, allowing the grid to maintain
 *   existing columns or generate new ones based on the CSV file's first row.
 * - Specification of permissible file extensions for imports to ensure compatibility and security.
 *
 * This type is crucial for applications that require flexible and controlled integration
 * of CSV data into RevoGrid, supporting a wide range of data handling scenarios.
 */
import {
  EXCEL_BEFORE_IMPORT_EVENT,
  EXCEL_BEFORE_SET_EVENT,
  EXCEL_EXPORT_EVENT,
} from '../events';
import type {
  ExcelCsvBeforeImportEvent,
  ExcelCsvBeforeSetEvent,
  ExportExcelEvent,
} from './export-excel-event.type';
import type {
  ExcelExportContextTransformer,
  ExcelExportProviderRef,
} from './export-excel-provider.type';

export type ExcelConfig = {

  /** Allow CSV drag and drop files to the grid area. Default: `true`. */
  allowDrag?: boolean;

  /**
   * Grid-level default export provider.
   *
   * `plugin.export({ provider })` still wins for one-off exports. When omitted,
   * the bundled `write-excel-file` provider is used.
   */
  exportProvider?: ExcelExportProviderRef;

  /**
   * Grid-level Excel export transforms for every export call.
   *
   * These run after the plugin prepares the provider context and applies
   * built-in Pro transforms, but before one-off
   * `plugin.export({ exportTransformers })` transforms. Use them for
   * application-wide workbook formatting, provider-option defaults, or
   * provider metadata that should apply consistently to all Excel exports.
   */
  exportTransformers?: ExcelExportContextTransformer[];

  /**
   * Keep existing grid columns during CSV import instead of generating columns
   * from the first CSV row. Default: `false`.
   */
  skipColumnGeneration?: boolean;

  /** Allowed file extensions for CSV import. Default: `['.csv']`. */
  allowedExtensions?: string[];
};


declare global {
  interface HTMLRevoGridElement {
    exportExcel?: ExcelConfig;
    'export-excel'?: ExcelConfig;
  }

  interface HTMLRevoGridElementEventMap {
    /**
     * Event for export excel
     *
     * @example
     * ```typescript
     * grid.addEventListener(EXCEL_EXPORT_EVENT, (event) => {
     *   console.log(event);
     * });
     */
    [EXCEL_EXPORT_EVENT]: ExportExcelEvent | undefined;
    [EXCEL_BEFORE_IMPORT_EVENT]: ExcelCsvBeforeImportEvent;
    [EXCEL_BEFORE_SET_EVENT]: ExcelCsvBeforeSetEvent;
  }
}

declare module '@revolist/revogrid' {
  export interface AdditionalData {
    /**
     * Additional data property for export excel
     *
     * @deprecated Use `grid.exportExcel` instead.
     *
     * @example
     * ```typescript
     * const grid = document.createElement('revo-grid');
     * grid.additionalData = { excel: { allowDrag: false } };
     * ```
     */
    excel?: ExcelConfig;
  }
}

Import Options

Option	Default	Description
allowDrag	true	Enables CSV drag/drop import unless the grid is readonly
allowedExtensions	['.csv']	Case-insensitive filename suffixes accepted in addition to files whose MIME type is text/csv
skipColumnGeneration	false	Keeps current grid columns and maps CSV cells by current column order

When skipColumnGeneration is false, the first CSV row becomes generated grid columns:

Name,Status
Ada,Open
Grace,Closed

The imported grid receives columns similar to:

[
  { prop: 0, name: 'Name' },
  { prop: 1, name: 'Status' },
]

When skipColumnGeneration is true, all CSV rows are imported as data and mapped to the existing export column order:

grid.columns = [
  { prop: 'name', name: 'Name' },
  { prop: 'status', name: 'Status' },
];

await excel.importFile(file, {
  skipColumnGeneration: true,
});

Plugin Methods

Use importFile() when import is triggered by an app-owned upload control:

const plugins = await grid.getPlugins();
const excel = plugins.find((plugin) => plugin instanceof ExportExcelPlugin);

await excel?.importFile(file, {
  allowedExtensions: ['.csv', '.txt'],
  skipColumnGeneration: true,
});

Use isCsv() to validate a file before import:

if (excel?.isCsv(file, ['.csv'])) {
  await excel.importFile(file);
}

isExcel() remains as a deprecated compatibility alias. It is CSV-only and returns false for .xlsx files unless the caller explicitly allows that extension. It does not parse workbook files.

Acceptance is MIME-or-suffix based: isCsvFile() returns true when file.type is text/csv or the lower-cased filename ends with one of allowedExtensions. The configured suffixes are not a strict allowlist for files already identified with the CSV MIME type. Adding .txt or .xlsx only permits that filename suffix to enter the CSV text parser; it does not add a new parser.

Import Events

Before applying imported rows, the plugin dispatches CSV-oriented events:

Event	Detail
excel-before-import	file, sheetName, csv, and parsed rows
excel-before-set	All import detail plus mapped jsonData

sheetName is a compatibility label and contains the filename.

Prevent either event to cancel replacing the grid source:

grid.addEventListener('excel-before-set', (event) => {
  const { jsonData } = event.detail;

  if (!jsonData.length) {
    event.preventDefault();
  }
});

Parser Behavior

The default importer reads files with FileReader.readAsText and parses CSV values. It handles BOMs, CRLF/LF line endings, quoted values, escaped quotes, empty cells, and trailing blank lines.

When a file matches neither the CSV MIME type nor an allowed suffix, the plugin logs Only CSV files are supported. and returns without changing the grid. File-reading or parsing failures are caught, logged as Failed to load CSV file:, and also resolve importFile() without throwing. If your UI needs a rejected promise or a user-visible error state, validate and read the file in app code before calling the plugin. If the grid is readonly or allowDrag is false, drag/drop import does not activate.

For .xlsx uploads, parse the workbook outside the plugin and assign normalized data:

const { columns, rows } = await parseWorkbook(file);

grid.columns = columns;
grid.source = rows;