Skip to content

Export to CSV

Export your grid’s values to the CSV format, as a downloadable file, a Blob, or a string. CSV holds values only: no formulas, styling, or number formatting, so a formula cell exports its computed result.

Prerequisites

  • Register the ExportFile plugin (it is part of registerAllModules()). The export methods work without any exportFile setting; set exportFile to any value, for example exportFile: true, to add the Export item to the default context menu; with a custom contextMenu item list, include 'export_file'.
  • The first two examples hide rows and columns 1, 3, and 5, with indicators on, so you can see which export includes them.

Steps

  1. Download a file

    downloadFile('csv', options) builds the file and starts the download. This example includes the hidden rows and columns.

    JavaScript
    import { useRef } from 'react';
    import { HotTable } from '@handsontable/react-wrapper';
    import { registerAllModules } from 'handsontable/registry';
    // register Handsontable's modules
    registerAllModules();
    const data = [
    ['Spring Launch', 'Email', 'North America', '1240', '4.2%', '$12000', 'Q1 2025'],
    ['Partner Webinar', 'Paid Search', 'EMEA', '860', '6.1%', '$9400', 'Q1 2025'],
    ['Summer Upsell', 'Social', 'APAC', '1520', '3.7%', '$13800', 'Q2 2025'],
    ['Product Video', 'Email', 'North America', '980', '5.4%', '$8600', 'Q2 2025'],
    ['Back-to-School', 'Display', 'LATAM', '1110', '4.8%', '$10100', 'Q3 2025'],
    ['Holiday Teaser', 'Affiliate', 'EMEA', '1340', '5.9%', '$12700', 'Q4 2025'],
    ['Loyalty Drive', 'SMS', 'APAC', '790', '7.3%', '$6200', 'Q4 2025'],
    ];
    const ExampleComponent = () => {
    const hotRef = useRef(null);
    const buttonClickCallback = () => {
    const hot = hotRef.current?.hotInstance;
    const exportPlugin = hot?.getPlugin('exportFile');
    exportPlugin?.downloadFile('csv', {
    colHeaders: true,
    rowHeaders: true,
    exportHiddenColumns: true,
    exportHiddenRows: true,
    filename: 'Campaigns_[YYYY]-[MM]-[DD]',
    });
    };
    return (
    <>
    <div className="example-controls-container">
    <div className="controls">
    <button id="export-file" onClick={() => buttonClickCallback()}>
    Download CSV
    </button>
    </div>
    </div>
    <HotTable
    // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
    ref={hotRef}
    data={data}
    colHeaders={true}
    rowHeaders={true}
    hiddenRows={{ rows: [1, 3, 5], indicators: true }}
    hiddenColumns={{ columns: [1, 3, 5], indicators: true }}
    height="auto"
    autoWrapRow={true}
    autoWrapCol={true}
    />
    </>
    );
    };
    export default ExampleComponent;
    TypeScript
    import { useRef } from 'react';
    import { HotTable, HotTableRef } from '@handsontable/react-wrapper';
    import { registerAllModules } from 'handsontable/registry';
    // register Handsontable's modules
    registerAllModules();
    const data = [
    ['Spring Launch', 'Email', 'North America', '1240', '4.2%', '$12000', 'Q1 2025'],
    ['Partner Webinar', 'Paid Search', 'EMEA', '860', '6.1%', '$9400', 'Q1 2025'],
    ['Summer Upsell', 'Social', 'APAC', '1520', '3.7%', '$13800', 'Q2 2025'],
    ['Product Video', 'Email', 'North America', '980', '5.4%', '$8600', 'Q2 2025'],
    ['Back-to-School', 'Display', 'LATAM', '1110', '4.8%', '$10100', 'Q3 2025'],
    ['Holiday Teaser', 'Affiliate', 'EMEA', '1340', '5.9%', '$12700', 'Q4 2025'],
    ['Loyalty Drive', 'SMS', 'APAC', '790', '7.3%', '$6200', 'Q4 2025'],
    ];
    const ExampleComponent = () => {
    const hotRef = useRef<HotTableRef>(null);
    const buttonClickCallback = () => {
    const hot = hotRef.current?.hotInstance;
    const exportPlugin = hot?.getPlugin('exportFile');
    exportPlugin?.downloadFile('csv', {
    colHeaders: true,
    rowHeaders: true,
    exportHiddenColumns: true,
    exportHiddenRows: true,
    filename: 'Campaigns_[YYYY]-[MM]-[DD]',
    });
    };
    return (
    <>
    <div className="example-controls-container">
    <div className="controls">
    <button id="export-file" onClick={() => buttonClickCallback()}>
    Download CSV
    </button>
    </div>
    </div>
    <HotTable
    // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
    ref={hotRef}
    data={data}
    colHeaders={true}
    rowHeaders={true}
    hiddenRows={{ rows: [1, 3, 5], indicators: true }}
    hiddenColumns={{ columns: [1, 3, 5], indicators: true }}
    height="auto"
    autoWrapRow={true}
    autoWrapCol={true}
    />
    </>
    );
    };
    export default ExampleComponent;
  2. Export as a Blob or a string

    exportAsBlob('csv', options) returns a Blob, for example to upload; exportAsString('csv', options) returns the text. This example leaves the hidden rows and columns out. Open the browser console to see the result.

    JavaScript
    import { useRef } from 'react';
    import { HotTable } from '@handsontable/react-wrapper';
    import { registerAllModules } from 'handsontable/registry';
    // register Handsontable's modules
    registerAllModules();
    const data = [
    ['Spring Launch', 'Email', 'North America', '1240', '4.2%', '$12000', 'Q1 2025'],
    ['Partner Webinar', 'Paid Search', 'EMEA', '860', '6.1%', '$9400', 'Q1 2025'],
    ['Summer Upsell', 'Social', 'APAC', '1520', '3.7%', '$13800', 'Q2 2025'],
    ['Product Video', 'Email', 'North America', '980', '5.4%', '$8600', 'Q2 2025'],
    ['Back-to-School', 'Display', 'LATAM', '1110', '4.8%', '$10100', 'Q3 2025'],
    ['Holiday Teaser', 'Affiliate', 'EMEA', '1340', '5.9%', '$12700', 'Q4 2025'],
    ['Loyalty Drive', 'SMS', 'APAC', '790', '7.3%', '$6200', 'Q4 2025'],
    ];
    // Hidden rows and columns stay out of both exports.
    const options = {
    colHeaders: true,
    rowHeaders: true,
    exportHiddenColumns: false,
    exportHiddenRows: false,
    };
    const ExampleComponent = () => {
    const hotRef = useRef(null);
    const exportBlob = () => {
    const exportPlugin = hotRef.current?.hotInstance?.getPlugin('exportFile');
    console.log(exportPlugin?.exportAsBlob('csv', options));
    };
    const exportString = () => {
    const exportPlugin = hotRef.current?.hotInstance?.getPlugin('exportFile');
    console.log(exportPlugin?.exportAsString('csv', options));
    };
    return (
    <>
    <div className="example-controls-container">
    <div className="controls">
    <button id="export-blob" onClick={exportBlob}>
    Export as a Blob
    </button>
    <button id="export-string" onClick={exportString}>
    Export as a string
    </button>
    </div>
    </div>
    <HotTable
    // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
    ref={hotRef}
    data={data}
    colHeaders={true}
    rowHeaders={true}
    hiddenRows={{ rows: [1, 3, 5], indicators: true }}
    hiddenColumns={{ columns: [1, 3, 5], indicators: true }}
    height="auto"
    autoWrapRow={true}
    autoWrapCol={true}
    />
    </>
    );
    };
    export default ExampleComponent;
    TypeScript
    import { useRef } from 'react';
    import { HotTable, HotTableRef } from '@handsontable/react-wrapper';
    import { registerAllModules } from 'handsontable/registry';
    // register Handsontable's modules
    registerAllModules();
    const data = [
    ['Spring Launch', 'Email', 'North America', '1240', '4.2%', '$12000', 'Q1 2025'],
    ['Partner Webinar', 'Paid Search', 'EMEA', '860', '6.1%', '$9400', 'Q1 2025'],
    ['Summer Upsell', 'Social', 'APAC', '1520', '3.7%', '$13800', 'Q2 2025'],
    ['Product Video', 'Email', 'North America', '980', '5.4%', '$8600', 'Q2 2025'],
    ['Back-to-School', 'Display', 'LATAM', '1110', '4.8%', '$10100', 'Q3 2025'],
    ['Holiday Teaser', 'Affiliate', 'EMEA', '1340', '5.9%', '$12700', 'Q4 2025'],
    ['Loyalty Drive', 'SMS', 'APAC', '790', '7.3%', '$6200', 'Q4 2025'],
    ];
    // Hidden rows and columns stay out of both exports.
    const options = {
    colHeaders: true,
    rowHeaders: true,
    exportHiddenColumns: false,
    exportHiddenRows: false,
    };
    const ExampleComponent = () => {
    const hotRef = useRef<HotTableRef>(null);
    const exportBlob = () => {
    const exportPlugin = hotRef.current?.hotInstance?.getPlugin('exportFile');
    console.log(exportPlugin?.exportAsBlob('csv', options));
    };
    const exportString = () => {
    const exportPlugin = hotRef.current?.hotInstance?.getPlugin('exportFile');
    console.log(exportPlugin?.exportAsString('csv', options));
    };
    return (
    <>
    <div className="example-controls-container">
    <div className="controls">
    <button id="export-blob" onClick={exportBlob}>
    Export as a Blob
    </button>
    <button id="export-string" onClick={exportString}>
    Export as a string
    </button>
    </div>
    </div>
    <HotTable
    // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
    ref={hotRef}
    data={data}
    colHeaders={true}
    rowHeaders={true}
    hiddenRows={{ rows: [1, 3, 5], indicators: true }}
    hiddenColumns={{ columns: [1, 3, 5], indicators: true }}
    height="auto"
    autoWrapRow={true}
    autoWrapCol={true}
    />
    </>
    );
    };
    export default ExampleComponent;
  3. Prevent CSV injection

    A spreadsheet application reads a CSV cell that starts with =, +, -, or @ as a formula (OWASP: CSV injection). Set the sanitizeValues option when the data comes from users. This example shows the four modes.

    JavaScript
    import { useRef } from 'react';
    import { HotTable } from '@handsontable/react-wrapper';
    import { registerAllModules } from 'handsontable/registry';
    // register Handsontable's modules
    registerAllModules();
    const data = [
    ['https://api.acme-inventory.com/live-stock', '=WEBSERVICE("https://api.acme-inventory.com/live-stock")'],
    ['https://status.vertex-logistics.com/feed', '=WEBSERVICE("https://status.vertex-logistics.com/feed")'],
    ['http://malicious.example/payload.exe', '=CMD("| calc.exe")'],
    ['https://news.example.com/q2-briefing', '=HYPERLINK("http://malicious.example","Open report")'],
    ['https://cdn.example.com/daily.csv', '+SUM(1,1)'],
    ];
    const ExampleComponent = () => {
    const hotRef = useRef(null);
    const downloadWithNoSanitizationCallback = () => {
    const hot = hotRef.current?.hotInstance;
    const exportPlugin = hot?.getPlugin('exportFile');
    exportPlugin?.downloadFile('csv', {
    bom: false,
    columnDelimiter: ',',
    colHeaders: false,
    exportHiddenColumns: true,
    exportHiddenRows: true,
    fileExtension: 'csv',
    filename: 'Handsontable-CSV-file_[YYYY]-[MM]-[DD]',
    mimeType: 'text/csv',
    rowDelimiter: '\r\n',
    });
    };
    const downloadWithRecommendedSanitizationCallback = () => {
    const hot = hotRef.current?.hotInstance;
    const exportPlugin = hot?.getPlugin('exportFile');
    exportPlugin?.downloadFile('csv', {
    bom: false,
    columnDelimiter: ',',
    colHeaders: false,
    exportHiddenColumns: true,
    exportHiddenRows: true,
    fileExtension: 'csv',
    filename: 'Handsontable-CSV-file_[YYYY]-[MM]-[DD]',
    mimeType: 'text/csv',
    rowDelimiter: '\r\n',
    sanitizeValues: true,
    });
    };
    const downloadWithRegexpSanitizationCallback = () => {
    const hot = hotRef.current?.hotInstance;
    const exportPlugin = hot?.getPlugin('exportFile');
    exportPlugin?.downloadFile('csv', {
    bom: false,
    columnDelimiter: ',',
    colHeaders: false,
    exportHiddenColumns: true,
    exportHiddenRows: true,
    fileExtension: 'csv',
    filename: 'Handsontable-CSV-file_[YYYY]-[MM]-[DD]',
    mimeType: 'text/csv',
    rowDelimiter: '\r\n',
    sanitizeValues: /WEBSERVICE|CMD|HYPERLINK|^\+/,
    });
    };
    const downloadWithFunctionSanitizationCallback = () => {
    const hot = hotRef.current?.hotInstance;
    const exportPlugin = hot?.getPlugin('exportFile');
    exportPlugin?.downloadFile('csv', {
    bom: false,
    columnDelimiter: ',',
    colHeaders: false,
    exportHiddenColumns: true,
    exportHiddenRows: true,
    fileExtension: 'csv',
    filename: 'Handsontable-CSV-file_[YYYY]-[MM]-[DD]',
    mimeType: 'text/csv',
    rowDelimiter: '\r\n',
    sanitizeValues: (value) => {
    return /WEBSERVICE|CMD|HYPERLINK|^\+/.test(value) ? 'REMOVED SUSPICIOUS CELL CONTENT' : value;
    },
    });
    };
    return (
    <>
    <div className="example-controls-container">
    <div className="controls">
    <button onClick={() => downloadWithNoSanitizationCallback()}>Download CSV with no sanitization</button>
    <button onClick={() => downloadWithRecommendedSanitizationCallback()}>
    Download CSV with recommended sanitization
    </button>
    <button onClick={() => downloadWithRegexpSanitizationCallback()}>
    Download CSV with sanitization using a regexp
    </button>
    <button onClick={() => downloadWithFunctionSanitizationCallback()}>
    Download CSV with sanitization using a function
    </button>
    </div>
    </div>
    <HotTable
    // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
    ref={hotRef}
    data={data}
    colHeaders={true}
    rowHeaders={true}
    height="auto"
    autoWrapRow={true}
    autoWrapCol={true}
    />
    </>
    );
    };
    export default ExampleComponent;
    TypeScript
    import { useRef } from 'react';
    import { HotTable, HotTableRef } from '@handsontable/react-wrapper';
    import { registerAllModules } from 'handsontable/registry';
    // register Handsontable's modules
    registerAllModules();
    const data = [
    ['https://api.acme-inventory.com/live-stock', '=WEBSERVICE("https://api.acme-inventory.com/live-stock")'],
    ['https://status.vertex-logistics.com/feed', '=WEBSERVICE("https://status.vertex-logistics.com/feed")'],
    ['http://malicious.example/payload.exe', '=CMD("| calc.exe")'],
    ['https://news.example.com/q2-briefing', '=HYPERLINK("http://malicious.example","Open report")'],
    ['https://cdn.example.com/daily.csv', '+SUM(1,1)'],
    ];
    const ExampleComponent = () => {
    const hotRef = useRef<HotTableRef>(null);
    const downloadWithNoSanitizationCallback = () => {
    const hot = hotRef.current?.hotInstance;
    const exportPlugin = hot?.getPlugin('exportFile');
    exportPlugin?.downloadFile('csv', {
    bom: false,
    columnDelimiter: ',',
    colHeaders: false,
    exportHiddenColumns: true,
    exportHiddenRows: true,
    fileExtension: 'csv',
    filename: 'Handsontable-CSV-file_[YYYY]-[MM]-[DD]',
    mimeType: 'text/csv',
    rowDelimiter: '\r\n',
    });
    };
    const downloadWithRecommendedSanitizationCallback = () => {
    const hot = hotRef.current?.hotInstance;
    const exportPlugin = hot?.getPlugin('exportFile');
    exportPlugin?.downloadFile('csv', {
    bom: false,
    columnDelimiter: ',',
    colHeaders: false,
    exportHiddenColumns: true,
    exportHiddenRows: true,
    fileExtension: 'csv',
    filename: 'Handsontable-CSV-file_[YYYY]-[MM]-[DD]',
    mimeType: 'text/csv',
    rowDelimiter: '\r\n',
    sanitizeValues: true,
    });
    };
    const downloadWithRegexpSanitizationCallback = () => {
    const hot = hotRef.current?.hotInstance;
    const exportPlugin = hot?.getPlugin('exportFile');
    exportPlugin?.downloadFile('csv', {
    bom: false,
    columnDelimiter: ',',
    colHeaders: false,
    exportHiddenColumns: true,
    exportHiddenRows: true,
    fileExtension: 'csv',
    filename: 'Handsontable-CSV-file_[YYYY]-[MM]-[DD]',
    mimeType: 'text/csv',
    rowDelimiter: '\r\n',
    sanitizeValues: /WEBSERVICE|CMD|HYPERLINK|^\+/,
    });
    };
    const downloadWithFunctionSanitizationCallback = () => {
    const hot = hotRef.current?.hotInstance;
    const exportPlugin = hot?.getPlugin('exportFile');
    exportPlugin?.downloadFile('csv', {
    bom: false,
    columnDelimiter: ',',
    colHeaders: false,
    exportHiddenColumns: true,
    exportHiddenRows: true,
    fileExtension: 'csv',
    filename: 'Handsontable-CSV-file_[YYYY]-[MM]-[DD]',
    mimeType: 'text/csv',
    rowDelimiter: '\r\n',
    sanitizeValues: (value) => {
    return /WEBSERVICE|CMD|HYPERLINK|^\+/.test(value) ? 'REMOVED SUSPICIOUS CELL CONTENT' : value;
    },
    });
    };
    return (
    <>
    <div className="example-controls-container">
    <div className="controls">
    <button onClick={() => downloadWithNoSanitizationCallback()}>Download CSV with no sanitization</button>
    <button onClick={() => downloadWithRecommendedSanitizationCallback()}>
    Download CSV with recommended sanitization
    </button>
    <button onClick={() => downloadWithRegexpSanitizationCallback()}>
    Download CSV with sanitization using a regexp
    </button>
    <button onClick={() => downloadWithFunctionSanitizationCallback()}>
    Download CSV with sanitization using a function
    </button>
    </div>
    </div>
    <HotTable
    // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
    ref={hotRef}
    data={data}
    colHeaders={true}
    rowHeaders={true}
    height="auto"
    autoWrapRow={true}
    autoWrapCol={true}
    />
    </>
    );
    };
    export default ExampleComponent;

Result

You can export the grid as a file, a Blob, or a string, choose what the file holds, and keep user-provided values from running as formulas.

Options

Pass these options as the second argument of any export method.

OptionType, defaultDescription
bomboolean, truePrepend the UTF-8 byte order mark (EF BB BF). It is prepended to the string exportAsString() returns too.
colHeadersboolean, falseInclude the column headers. With nested headers, every layer becomes one header line. Column headers are always quoted. See Nested headers.
rowHeadersboolean, falseInclude the row headers as the first column.
exportHiddenColumns, exportHiddenRowsboolean, falseInclude hidden columns or rows. 'hide', which the XLSX export accepts, counts as false here.
rangenumber[], whole grid[startRow, startColumn, endRow, endColumn] in visual indexes.
columnDelimiterstring, ','Column delimiter. A value that holds it, a double quote, or a line break is quoted.
rowDelimiterstring, '\r\n'Row delimiter.
filenamestring, 'Handsontable [YYYY]-[MM]-[DD]'File name without the extension. The placeholders become the current date. Used by downloadFile() and downloadFileAsync().
fileExtensionstring, 'csv'File extension, used by the same two methods.
mimeTypestring, 'text/csv'MIME type of the Blob. The Blob’s type also carries ;charset= and the encoding option, text/csv;charset=utf-8 by default.
encodingstring, 'utf-8'Charset label of the Blob and the download. The content is always UTF-8.
sanitizeValuesboolean | RegExp | Function, falsetrue prefixes a value that starts with =, +, -, @, a tab, or a carriage return with ', following the OWASP rules. A RegExp prefixes the values it matches. A function receives the value and returns the replacement. Any of the three also quotes every non-empty cell.

Nested headers

With the nestedHeaders option, colHeaders: true exports every header layer. Each layer becomes one header line, and a group label repeats across every column it spans, so a spreadsheet shows the group above each of its columns.

const hot = new Handsontable(container, {
data: [[1, 2, 3, 4]],
colHeaders: true,
nestedHeaders: [
[{ label: '2024', colspan: 2 }, { label: '2025', colspan: 2 }],
['Q1', 'Q2', 'Q1', 'Q2'],
],
});
hot.getPlugin('exportFile').downloadFile('csv', { colHeaders: true });
// The file receives:
// "2024","2024","2025","2025"
// "Q1","Q2","Q1","Q2"
// 1,2,3,4

A group shrinks to the columns the export includes, so hidden columns follow exportHiddenColumns. A range that starts inside a group leaves that group’s cells empty on the parent line, so every header line keeps the data’s column count.

Headers as plain text

A column header is also its display string. A header of '<b>Total</b>' renders as Total, but the export writes the value it was given, so the file receives the literal <b>Total</b>. Set the grid’s textExtractor option to true to export the displayed text instead:

const hot = new Handsontable(container, {
data: [[1, 2]],
colHeaders: ['<b>Total</b>', 'Count'],
textExtractor: true,
});
hot.getPlugin('exportFile').downloadFile('csv', { colHeaders: true });
// The file receives:
// "Total","Count"
// 1,2

textExtractor is a grid option, not an export option. It applies to column, row, and nested headers, in CSV and in Excel. Cell values are left alone: a value such as a<b reaches the file unchanged.

Extraction turns HTML entities back into characters, so a header stored as &#61;SUM(A1) reaches the file as =SUM(A1), which a spreadsheet reads as a formula. Set sanitizeValues when you export headers from untrusted sources. To extract headers differently per surface, pass textExtractor a function (content, source) instead of true; source is 'ExportFile.rowHeader' for a row header and 'ExportFile.columnHeader' for a column header in an export, and 'CopyPaste.columnHeader' when headers are copied. Return content for any other source.

Methods

Each export method takes the format first, 'csv' or 'xlsx', and an options object second.

Get the plugin from the hotInstance of your HotTable ref: hotRef.current?.hotInstance?.getPlugin('exportFile'). See Instance methods.

Related guides

Related blog articles

Configuration options

Plugins