Skip to content

Import from CSV or Excel

In this tutorial, you will let users drop or pick a CSV or Excel (.xlsx) file, parse it in the browser, and preview column headers before loading rows into Handsontable DataGrid. You will learn how to use PapaParse for CSV and the built-in ImportFile plugin for Excel, infer column types, and show clear errors.

Overview

This recipe shows a small UI with:

  • A drag-and-drop zone and a hidden file input.
  • File type detection by extension (.csv vs .xlsx) and routing to the right parser.
  • PapaParse for CSV and the built-in ImportFile plugin for Excel workbooks.
  • A header preview before you commit data to the grid.
  • Clear error messages for wrong type, empty files, and malformed content.

Difficulty: Intermediate
Time: ~20 minutes
Libraries: papaparse (npm in the docs build; a CDN script at runtime for your own HTML pages). Excel needs none: the ImportFile plugin is part of Handsontable.

TypeScript
/* file: app.component.ts */
import { ChangeDetectorRef, Component, ViewChild, inject } from '@angular/core';
import { GridSettings, HotTableComponent, HotTableModule } from '@handsontable/angular-wrapper';
import Handsontable from 'handsontable/base';
import Papa from 'papaparse';
interface ParsedPayload {
headers: string[];
rows: Record<string, unknown>[];
}
function extensionOf(name: string): string {
const i = name.lastIndexOf('.');
return i >= 0 ? name.slice(i + 1).toLowerCase() : '';
}
function normalizeCellValue(value: unknown): unknown {
if (value === null || value === undefined) {
return null;
}
if (typeof value === 'number' || typeof value === 'boolean') {
return value;
}
if (value instanceof Date) {
return value.toISOString().slice(0, 10);
}
const text = String(value).trim();
return text === '' ? null : text;
}
function processPapaResults(results: Papa.ParseResult<Record<string, unknown>>): ParsedPayload {
if (results.errors.length > 0) {
throw new Error(results.errors[0].message || 'CSV parse error.');
}
const fields = (results.meta.fields ?? []).filter((f) => f !== undefined && f !== '');
if (fields.length === 0) {
throw new Error('No header row found in the CSV.');
}
const rows = results.data.map((row) => {
const out: Record<string, unknown> = {};
for (const key of fields) {
out[key] = normalizeCellValue(row[key]);
}
return out;
});
if (rows.length === 0) {
throw new Error('No data rows after the header.');
}
return { headers: fields, rows };
}
function parseCsvText(text: string): ParsedPayload {
const trimmed = text.trim();
if (!trimmed) {
throw new Error('The input is empty.');
}
const parsed = Papa.parse<Record<string, unknown>>(trimmed, {
header: true,
dynamicTyping: true,
skipEmptyLines: 'greedy',
transformHeader: (h) => h.trim(),
});
return processPapaResults(parsed);
}
async function parseCsvFile(file: File): Promise<ParsedPayload> {
return new Promise((resolve, reject) => {
Papa.parse<Record<string, unknown>>(file, {
header: true,
dynamicTyping: true,
skipEmptyLines: 'greedy',
transformHeader: (h: string) => h.trim(),
complete: (results: Papa.ParseResult<Record<string, unknown>>) => {
try {
resolve(processPapaResults(results));
} catch (e) {
reject(e instanceof Error ? e : new Error(String(e)));
}
},
error: (err: Error) => reject(err instanceof Error ? err : new Error(String(err))),
});
});
}
async function parseXlsxFile(file: File): Promise<ParsedPayload> {
// A throwaway grid in a hidden element runs the ImportFile plugin. `apply: false` returns the
// mapped sheet without touching the grid, and a refused file rejects with a message that says why.
const host = document.createElement('div');
host.hidden = true;
document.body.appendChild(host);
const parser = new Handsontable(host, {
data: [[]],
importFile: true,
// licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
});
try {
const result = await parser.getPlugin('importFile').importFromBlob('xlsx', file, {
colHeaders: 'firstRow',
apply: false,
});
const rawHeaders = (Array.isArray(result.colHeaders) ? result.colHeaders : []) as unknown[];
const headers = rawHeaders.map((cell, i) => {
const text = String(cell ?? '').trim();
return text === '' ? `Column ${i + 1}` : text;
});
if (headers.length === 0) {
throw new Error('No header row found in the Excel sheet.');
}
const rows: Record<string, unknown>[] = [];
for (const line of result.data as unknown[][]) {
const obj: Record<string, unknown> = {};
let allEmpty = true;
headers.forEach((key, c) => {
obj[key] = normalizeCellValue(line[c]);
allEmpty = allEmpty && obj[key] === null;
});
if (!allEmpty) {
rows.push(obj);
}
}
if (rows.length === 0) {
throw new Error('No data rows after the header.');
}
return { headers, rows };
} finally {
parser.destroy();
host.remove();
}
}
async function parseFile(file: File): Promise<ParsedPayload> {
const ext = extensionOf(file.name);
if (ext === 'csv') {
return parseCsvFile(file);
}
if (ext === 'xlsx') {
return parseXlsxFile(file);
}
throw new Error('Unsupported file type. Use a .csv or .xlsx file.');
}
@Component({
standalone: true,
imports: [HotTableModule],
selector: 'example1-import-csv-excel',
template: `
<div class="import-csv-excel-wrap">
<div
class="import-dropzone"
[class.import-dropzone--active]="isDragOver"
tabindex="0"
role="button"
aria-label="Drop a CSV or Excel file here"
(dragover)="onDragOver($event)"
(dragleave)="onDragLeave()"
(drop)="onDrop($event)"
>
<p>Drop a <code>.csv</code> or <code>.xlsx</code> file here, or pick a source.</p>
<div class="import-actions">
<label class="import-file-label">
<span>Choose file</span>
<input
type="file"
accept=".csv,.xlsx,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,text/csv"
(change)="onFileChange($event)"
#fileInput
/>
</label>
<button type="button" class="import-sample-btn" (click)="loadSampleData()">Load sample data</button>
</div>
</div>
@if (errorMessage) {
<div class="import-msg import-msg--error">{{ errorMessage }}</div>
}
@if (gridData.length === 0) {
<div class="import-empty">
<span class="import-empty-icon" aria-hidden="true">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<rect x="3" y="3" width="18" height="18"/>
<path d="M3 9h18M3 15h18M9 3v18M15 3v18"/>
</svg>
</span>
<p class="import-empty-title">No data loaded yet</p>
<p class="import-empty-text">
Drop a CSV or Excel file above, choose a file, or load the sample data to populate the table.
</p>
</div>
} @else {
<hot-table [data]="gridData" [settings]="gridSettings"></hot-table>
}
</div>
`,
})
export class AppComponent {
@ViewChild(HotTableComponent, { static: false }) readonly hotTable!: HotTableComponent;
private readonly cdr = inject(ChangeDetectorRef);
isDragOver = false;
errorMessage = '';
gridData: Record<string, unknown>[] = [];
private readonly SAMPLE_CSV = `Product,Category,In stock,Price
Widget A,Hardware,true,19.99
Widget B,Hardware,false,24.5
Service Pack,Services,true,0`;
gridSettings: GridSettings = {
colHeaders: [],
columns: [],
rowHeaders: true,
height: 'auto',
width: '100%',
};
onDragOver(event: DragEvent): void {
event.preventDefault();
this.isDragOver = true;
}
onDragLeave(): void {
this.isDragOver = false;
}
onDrop(event: DragEvent): void {
event.preventDefault();
this.isDragOver = false;
const file = event.dataTransfer?.files?.[0];
if (file) {
this.handleFile(file);
}
}
onFileChange(event: Event): void {
const input = event.target as HTMLInputElement;
const file = input.files?.[0];
if (file) {
this.handleFile(file);
}
input.value = '';
}
async loadSampleData(): Promise<void> {
this.errorMessage = '';
try {
const payload = parseCsvText(this.SAMPLE_CSV);
this.loadIntoGrid(payload);
} catch (e) {
this.errorMessage = e instanceof Error ? e.message : String(e);
}
}
private async handleFile(file: File): Promise<void> {
this.errorMessage = '';
if (file.size === 0) {
this.errorMessage = 'The file is empty.';
return;
}
try {
const payload = await parseFile(file);
this.loadIntoGrid(payload);
} catch (e) {
this.errorMessage = e instanceof Error ? e.message : String(e);
} finally {
this.cdr.markForCheck();
}
}
private loadIntoGrid(payload: ParsedPayload): void {
const { headers, rows } = payload;
this.gridSettings = {
...this.gridSettings,
colHeaders: headers,
columns: this.columnsFromHeaders(headers, rows),
};
this.gridData = [...rows];
}
private columnsFromHeaders(headers: string[], rows: Record<string, unknown>[]): GridSettings['columns'] {
return headers.map((data) => {
const values = rows
.map((row) => row[data])
.filter((v) => v !== null);
if (values.length > 0 && values.every((v) => typeof v === 'number')) {
return { data, type: 'numeric' };
}
if (values.length > 0 && values.every((v) => typeof v === 'boolean')) {
return { data, type: 'checkbox' };
}
return { data, type: 'text' };
});
}
}
/* end-file */
/* file: app.config.ts */
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
import { registerAllModules } from 'handsontable/registry';
import { HOT_GLOBAL_CONFIG, HotGlobalConfig } from '@handsontable/angular-wrapper';
registerAllModules();
export const appConfig: ApplicationConfig = {
providers: [
provideZoneChangeDetection({ eventCoalescing: true }),
{
provide: HOT_GLOBAL_CONFIG,
useValue: {
// license: 'your-license-key', // get a key at https://handsontable.com/pricing/
} as HotGlobalConfig,
},
],
};
/* end-file */
HTML
<div><example1-import-csv-excel></example1-import-csv-excel></div>
CSS
.import-csv-excel-wrap {
display: flex;
flex-direction: column;
margin: 0 -1rem;
}
.import-dropzone {
padding: 1.5rem 1rem;
text-align: center;
border: 0;
border-bottom: 1px solid var(--sl-color-gray-5, #e0e0e0);
border-radius: 0;
background: transparent;
color: var(--sl-color-gray-2, #555555);
font-size: var(--sl-text-xs, 0.75rem);
transition: background 0.15s ease;
cursor: pointer;
}
.import-dropzone p {
margin: 0 0 0.75rem;
}
.import-dropzone.import-dropzone--active {
background: var(--sl-color-gray-6, #eeeeee);
}
.import-actions {
display: inline-flex;
align-items: center;
gap: 0.5rem;
}
.import-file-label {
display: inline-block;
cursor: pointer;
}
.import-file-label span,
.import-sample-btn {
display: inline-flex;
align-items: center;
padding: 0.375rem 0.75rem;
border: 1px solid var(--sl-color-gray-5, #e0e0e0);
border-radius: 0;
background: var(--sl-color-gray-6, #eeeeee);
color: var(--sl-color-gray-2, #555555);
font-family: var(--sl-font, Inter, system-ui, -apple-system, sans-serif);
font-size: var(--sl-text-xs, 0.75rem);
font-weight: 500;
line-height: 1.4;
cursor: pointer;
transition: background-color 0.15s, color 0.15s, border-color 0.15s;
}
.import-file-label:hover span,
.import-sample-btn:hover {
background: var(--sl-color-gray-5, #e0e0e0);
color: var(--sl-color-white, #333333);
}
.import-file-label input {
position: absolute;
width: 1px;
height: 1px;
opacity: 0;
pointer-events: none;
}
.import-msg {
margin: 0;
padding: 0.75rem 1rem;
border-radius: 0;
font-size: var(--sl-text-xs, 0.75rem);
}
.import-msg--error {
border-bottom: 1px solid var(--sl-color-red, #ef4444);
background: var(--sl-color-red-low, rgba(239, 68, 68, 0.12));
color: var(--sl-color-red, #ef4444);
}
.import-empty {
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
gap: 0.5rem;
padding: 2.5rem 1rem;
min-height: 200px;
color: var(--sl-color-gray-2, #555555);
text-align: center;
}
.import-empty-icon {
display: inline-flex;
align-items: center;
justify-content: center;
width: 40px;
height: 40px;
margin-bottom: 0.25rem;
border: 1px solid var(--sl-color-gray-5, #e0e0e0);
color: var(--sl-color-gray-3, #777777);
}
.import-empty-title {
margin: 0;
color: var(--sl-color-white, #333333);
font-size: var(--sl-text-sm, 0.875rem);
font-weight: 600;
}
.import-empty-text {
margin: 0;
max-width: 38ch;
font-size: var(--sl-text-xs, 0.75rem);
line-height: 1.5;
}

In Angular, call markForCheck() on an injected ChangeDetectorRef after you apply the parsed rows, as handleFile does. Angular 22 components are OnPush by default, and nothing marks the component dirty after the await. Without the call, the grid does not update until the next DOM event.

CDN scripts (no bundler)

For a plain HTML page, load Handsontable plus PapaParse from a CDN (pin the version to match what you test):

<script src="https://cdn.jsdelivr.net/npm/papaparse@5.7.0/papaparse.min.js"></script>

The JavaScript and React examples load the same URL on demand when window.Papa is missing, so the pattern matches a script-tag setup. The Angular and Vue examples import papaparse from npm instead.

  1. Accept files and detect type

    Use accept on the file input and check file.name to route .csv and .xlsx to the right parser. Reject everything else with a short message.

    The file input and drop zone (template)

    The drop zone is part of the component’s inline template:

    <div
    class="import-dropzone"
    [class.import-dropzone--active]="isDragOver"
    tabindex="0"
    role="button"
    aria-label="Drop a CSV or Excel file here"
    (dragover)="onDragOver($event)"
    (dragleave)="onDragLeave()"
    (drop)="onDrop($event)"
    >
    <p>Drop a <code>.csv</code> or <code>.xlsx</code> file here, or pick a source.</p>
    <div class="import-actions">
    <label class="import-file-label">
    <span>Choose file</span>
    <input
    type="file"
    accept=".csv,.xlsx,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,text/csv"
    (change)="onFileChange($event)"
    #fileInput
    />
    </label>
    <button type="button" class="import-sample-btn" (click)="loadSampleData()">Load sample data</button>
    </div>
    </div>

    What’s happening:

    • The accept attribute restricts the system file picker to .csv and .xlsx. This is a hint to the browser only — you must validate the extension in code as well.
    • The real <input> is visually hidden (a 1 px, absolutely positioned element with opacity: 0) and activated via the wrapping <label>. Clicking Choose file triggers the file picker without requiring a separate button.
    • Load sample data calls loadSampleData(), which parses a bundled CSV string so users can try the grid without having to upload a file first.
    • The drop zone has tabindex="0" and role="button", so keyboard users can focus it. It has no key handler; keyboard users open the file picker with Choose file.
    • [class.import-dropzone--active] follows the isDragOver field, which the drag handlers below set.

    Extension detection

    function extensionOf(name) {
    const i = name.lastIndexOf('.');
    return i >= 0 ? name.slice(i + 1).toLowerCase() : '';
    }

    What’s happening:

    • Takes the file name and returns the lowercase extension ("csv", "xlsx", or "" if there is none).
    • lastIndexOf('.') handles names like report.v2.csv correctly by taking the final dot.
    • The result is compared in parseFile and an error is thrown for anything that is not .csv or .xlsx.

    Wiring up file events

    The template event bindings call these AppComponent methods:

    isDragOver = false;
    onDragOver(event: DragEvent): void {
    event.preventDefault();
    this.isDragOver = true;
    }
    onDragLeave(): void {
    this.isDragOver = false;
    }
    onDrop(event: DragEvent): void {
    event.preventDefault();
    this.isDragOver = false;
    const file = event.dataTransfer?.files?.[0];
    if (file) {
    this.handleFile(file);
    }
    }
    onFileChange(event: Event): void {
    const input = event.target as HTMLInputElement;
    const file = input.files?.[0];
    if (file) {
    this.handleFile(file);
    }
    input.value = '';
    }

    What’s happening:

    • Both code paths (file input change and drop zone drop) hand the File object to the same handleFile method.
    • event.preventDefault() on dragover is required — without it the browser opens the file instead of passing it to the drop handler.
    • Setting isDragOver toggles the import-dropzone--active class, which gives visual feedback while a file is dragged over the zone.
    • Resetting input.value = '' after processing allows the user to import the same file a second time.
  2. Parse CSV with PapaParse

    Import PapaParse from npm

    import Papa from 'papaparse';

    What’s happening:

    • The Angular example installs papaparse from npm and imports it at the top of app.component.ts, so the parser is part of the bundle and no script is loaded at runtime.
    • The parse functions call Papa directly instead of receiving it as an argument.

    Parse a CSV file

    async function parseCsvFile(file: File): Promise<ParsedPayload> {
    return new Promise((resolve, reject) => {
    Papa.parse<Record<string, unknown>>(file, {
    header: true,
    dynamicTyping: true,
    skipEmptyLines: 'greedy',
    transformHeader: (h: string) => h.trim(),
    complete: (results: Papa.ParseResult<Record<string, unknown>>) => {
    try {
    resolve(processPapaResults(results));
    } catch (e) {
    reject(e instanceof Error ? e : new Error(String(e)));
    }
    },
    error: (err: Error) => reject(err instanceof Error ? err : new Error(String(err))),
    });
    });
    }

    What’s happening:

    • header: true tells PapaParse to treat the first row as column names and return each subsequent row as a plain object keyed by those names. results.meta.fields contains the ordered list of column names.
    • skipEmptyLines: 'greedy' drops rows that are entirely whitespace — handy for files with trailing newlines.
    • transformHeader: (h) => h.trim() removes accidental leading/trailing spaces from column names.
    • After parsing, empty or missing cell values are normalized to null so Handsontable displays a blank cell rather than the string "undefined" or "null".
    • dynamicTyping: true lets PapaParse return native numbers and booleans where possible.
    • Numeric and boolean values are preserved as-is; string values are trimmed, and empty strings are normalized to null.

    Parse a CSV text string (for the bundled sample)

    function parseCsvText(text: string): ParsedPayload {
    const trimmed = text.trim();
    if (!trimmed) {
    throw new Error('The input is empty.');
    }
    const parsed = Papa.parse<Record<string, unknown>>(trimmed, {
    header: true,
    dynamicTyping: true,
    skipEmptyLines: 'greedy',
    transformHeader: (h) => h.trim(),
    });
    return processPapaResults(parsed);
    }

    What’s happening:

    • Works identically to parseCsvFile but accepts a raw CSV string instead of a File object.
    • PapaParse’s synchronous parse(string, opts) overload is used here (no complete callback needed).
    • Used when the user clicks Load sample data to parse a CSV string embedded in the component and feed it into the grid.
  3. Parse Excel with the ImportFile plugin

    Read the workbook without a library

    The built-in ImportFile plugin reads .xlsx files, so Excel needs no parser of its own. The plugin runs on a grid, so the parser creates a throwaway one in a hidden element and destroys it afterwards:

    async function parseXlsxFile(file) {
    const host = document.createElement('div');
    host.hidden = true;
    document.body.appendChild(host);
    const parser = new Handsontable(host, {
    data: [[]],
    importFile: true,
    // licenseKey: 'your-license-key', // get a key at https://handsontable.com/pricing/
    });
    try {
    const result = await parser.getPlugin('importFile').importFromBlob('xlsx', file, {
    colHeaders: 'firstRow',
    apply: false,
    });
    const headers = (result.colHeaders ?? []).map((cell, i) => {
    const text = String(cell ?? '').trim();
    return text === '' ? `Column ${i + 1}` : text;
    });
    if (headers.length === 0) {
    throw new Error('No header row found in the Excel sheet.');
    }
    const rows = [];
    for (const line of result.data) {
    const obj = {};
    let allEmpty = true;
    headers.forEach((key, c) => {
    obj[key] = normalizeCellValue(line[c]);
    allEmpty = allEmpty && obj[key] === null;
    });
    if (!allEmpty) {
    rows.push(obj);
    }
    }
    if (rows.length === 0) {
    throw new Error('No data rows after the header.');
    }
    return { headers, rows };
    } finally {
    parser.destroy();
    host.remove();
    }
    }

    What’s happening:

    1. importFromBlob('xlsx', file, { colHeaders: 'firstRow', apply: false }) reads the first sheet and returns the mapped result without touching the grid: result.colHeaders holds the promoted header row and result.data the rows below it.
    2. A refused file (an .xls, a password-protected workbook, a damaged archive) rejects with the plugin’s own message, and handleFile shows it as it is. For an .xls or a password-protected file, the message says to save it as an unprotected .xlsx.
    3. Empty header cells get a fallback name (Column 1, Column 2, …), and rows that are entirely empty are skipped, so both parsers return the same { headers, rows } shape.
    4. normalizeCellValue keeps numbers and booleans, keeps the YYYY-MM-DD strings the plugin derives for date cells, trims other text, and turns blank cells into null.
    5. The throwaway grid is destroyed in finally, so a rejected file does not leak it. To import straight into a visible grid, with cell types, merges, and formulas (formulas need the Formulas plugin), call the same method on that grid without apply: false.

    Route to the right parser

    async function parseFile(file: File): Promise<ParsedPayload> {
    const ext = extensionOf(file.name);
    if (ext === 'csv') {
    return parseCsvFile(file);
    }
    if (ext === 'xlsx') {
    return parseXlsxFile(file);
    }
    throw new Error('Unsupported file type. Use a .csv or .xlsx file.');
    }

    What’s happening:

    • extensionOf extracts the lowercase extension. Only .csv and .xlsx are handled; anything else throws immediately.
    • PapaParse is already bundled for CSV, and Excel goes through the built-in plugin, so nothing is downloaded at runtime.
    • Both parsers return the same shape: { headers: string[], rows: object[] } — the rest of the code does not need to know which parser ran.
  4. Load parsed data into the grid

    Build column definitions from header names

    function columnsFromHeaders(headers, rows) {
    return headers.map((data) => {
    const values = rows
    .map((row) => row[data])
    .filter((v) => v !== null);
    if (values.length > 0 && values.every((v) => typeof v === 'number')) {
    return { data, type: 'numeric' };
    }
    if (values.length > 0 && values.every((v) => typeof v === 'boolean')) {
    return { data, type: 'checkbox' };
    }
    return { data, type: 'text' };
    });
    }

    What’s happening:

    • Handsontable’s columns option expects an array of column descriptors. Each descriptor’s data property is the key used to read from the row objects.
    • The helper infers numeric and checkbox columns when all non-empty values in that column are numbers or booleans. Mixed columns stay as 'text'.

    Update the grid settings and data

    gridData: Record<string, unknown>[] = [];
    gridSettings: GridSettings = {
    colHeaders: [],
    columns: [],
    rowHeaders: true,
    height: 'auto',
    width: '100%',
    };
    private loadIntoGrid(payload: ParsedPayload): void {
    const { headers, rows } = payload;
    this.gridSettings = {
    ...this.gridSettings,
    colHeaders: headers,
    columns: this.columnsFromHeaders(headers, rows),
    };
    this.gridData = [...rows];
    }

    The template shows the grid only once there is data:

    @if (gridData.length === 0) {
    <div class="import-empty">
    <p class="import-empty-title">No data loaded yet</p>
    </div>
    } @else {
    <hot-table [data]="gridData" [settings]="gridSettings"></hot-table>
    }

    What’s happening:

    • loadIntoGrid assigns a new gridSettings object with the header names and the inferred column definitions, and a new gridData array. The <hot-table> bindings pass both to the grid, so you don’t call updateSettings or loadData yourself.
    • In the example, columnsFromHeaders is a private method of AppComponent with the same logic as the function above.
    • Until the first import, gridData is empty and @if shows the empty-state panel instead of a grid with a single blank cell. The example’s panel also holds an icon and a help text, left out here.

    Load the bundled sample

    private readonly SAMPLE_CSV = `Product,Category,In stock,Price
    Widget A,Hardware,true,19.99
    Widget B,Hardware,false,24.5
    Service Pack,Services,true,0`;
    async loadSampleData(): Promise<void> {
    this.errorMessage = '';
    try {
    const payload = parseCsvText(this.SAMPLE_CSV);
    this.loadIntoGrid(payload);
    } catch (e) {
    this.errorMessage = e instanceof Error ? e.message : String(e);
    }
    }

    What’s happening:

    • SAMPLE_CSV is a small CSV string stored on the component — enough to demonstrate the grid without forcing the user to upload anything.
    • PapaParse is already imported, so the method parses the sample synchronously and hands the result straight to loadIntoGrid — no preview step in between.
    • File uploads use the same loadIntoGrid method (see handleFile in Step 5), so both code paths converge on a single grid-population helper.
  5. Handle errors

    Error state

    errorMessage = '';
    @if (errorMessage) {
    <div class="import-msg import-msg--error">{{ errorMessage }}</div>
    }

    What’s happening:

    • The message is a component field, and @if renders the error panel only while it is non-empty — no empty box and no layout shift.
    • Angular escapes text in {{ errorMessage }}, so an error that echoes user-provided input cannot inject markup.

    All error conditions covered

    ConditionMessage
    Extension is not .csv or .xlsx"Unsupported file type. Use a .csv or .xlsx file."
    File has zero bytes"The file is empty."
    CSV has parse errorsFirst error message from PapaParse
    CSV has no header row"No header row found in the CSV."
    CSV has no data rows"No data rows after the header."
    Excel workbook refused (an .xls, a password-protected or damaged file, a workbook past the import limits)The ImportFile plugin’s own message
    Excel sheet is empty"No header row found in the Excel sheet."
    Excel has no data rows"No data rows after the header."

    The handleFile method is the single place where all file parse errors are caught and written to errorMessage:

    private readonly cdr = inject(ChangeDetectorRef);
    private async handleFile(file: File): Promise<void> {
    this.errorMessage = '';
    if (file.size === 0) {
    this.errorMessage = 'The file is empty.';
    return;
    }
    try {
    const payload = await parseFile(file);
    this.loadIntoGrid(payload);
    } catch (e) {
    this.errorMessage = e instanceof Error ? e.message : String(e);
    } finally {
    this.cdr.markForCheck();
    }
    }

    What’s happening:

    • file.size === 0 is checked before any async work to give an instant response for empty files.
    • Any error thrown by the parsers bubbles up here and is shown to the user.
    • On success, the parsed { headers, rows } payload goes straight to loadIntoGrid — no intermediate state to reset on failure.
    • markForCheck() in finally makes Angular render the new grid or the error after the await. Angular 22 components are OnPush by default, and nothing else marks the component dirty at that point.
    • The Load sample data method uses the same try/catch shape, so sample-parse errors surface in the same error panel.

Try it quickly

Click Load sample data in the example to populate the grid from the bundled CSV string, or save the snippet from Step 4 as sample.csv and drop it on the zone.

How it works - complete flow

  1. User picks or drops a file (or clicks Load sample data) — the change, drop, or sample button event fires and reaches handleFile / the sample handler.
  2. File size check — zero-byte files are rejected immediately (file path only).
  3. Extension routing — parseFile reads the extension, sends .csv to PapaParse, and sends .xlsx to the ImportFile plugin. The sample path always uses PapaParse via parseCsvText.
  4. Parsing — CSV goes through PapaParse with header: true; Excel goes through the built-in ImportFile plugin with apply: false, which returns the promoted header row and the rows below it.
  5. Normalization — empty cells become null, and native numbers/booleans are preserved for CSV and Excel.
  6. Grid population — loadIntoGrid replaces colHeaders, columns, and the data. The first load swaps the empty-state panel for the grid.
  7. Grid renders — Handsontable re-renders with the new columns and data.
  8. Errors at any step — caught by handleFile or the sample-parse handler and shown in the error panel.

What you learned

  • How to detect the file type by extension and route CSV files through PapaParse and Excel files through the built-in ImportFile plugin with a single handler function.
  • How to ship a bundled CSV sample so users can demo the grid without uploading a file first.
  • How to replace the column configuration and the data on every import, and how to keep the grid behind an empty-state panel until the first import.
  • How to handle errors at each stage — file size, parsing, and grid load — and surface them in a dedicated error panel.

Next steps