The simple, easy-to-implement library to export HTML tables to xlsx
, xls
, csv
, and txt
files.
- Migrating from 3.x to 4.x?
- Migrating from 4.x to 5.x?
v3
docs and README:v4
docs and README:v5
docs and README:
To use this library, include the FileSaver.js library, and TableExport library before the closing <body>
tag of your HTML document:
<script src="FileSaver.js"></script>
...
<script src="tableexport.js"></script>
$ bower install tableexport.js
$ npm install tableexport
uncompressed | compressed | |
---|---|---|
CSS | 🔗 | 🔗 |
JS | 🔗 | 🔗 |
Images | — | 🔗xlsx🔗xls🔗csv🔗txt |
In order to provide Office Open XML SpreadsheetML Format ( .xlsx
) support, you must include the following third-party library in your project before both FileSaver.js and TableExport.
- xlsx.core.js by SheetJS
Including
xlsx.core.js
is NOT necessary if installing withBower
ornpm
<script src="xlsx.core.js"></script>
<script src="FileSaver.js"></script>
...
<script src="tableexport.js"></script>
To support legacy browsers ( Chrome < 20, Firefox < 13, Opera < 12.10, IE < 10, Safari < 6 ) include the Blob.js polyfill before the FileSaver.js script.
- Blob.js by eligrey (forked by clarketm)
Including
Blob.js
is NOT necessary if installing withBower
ornpm
<script src="Blob.js"></script>
<script src="FileSaver.js"></script>
...
<script src="tableexport.js"></script>
To use this library, simple call the TableExport
constructor:
new TableExport(document.getElementsByTagName("table"));
// OR simply
TableExport(document.getElementsByTagName("table"));
// OR using jQuery
$("table").tableExport();
Additional properties can be passed-in to customize the look and feel of your tables, buttons, and exported data.
Notice that by default, TableExport will create export buttons for three different filetypes xls
, csv
, txt
. You can choose which buttons to generate by setting the formats
property to the filetype(s) of your choice.
/* Defaults */
TableExport(document.getElementsByTagName("table"), {
headers: true, // (Boolean), display table headers (th or td elements) in the <thead>, (default: true)
footers: true, // (Boolean), display table footers (th or td elements) in the <tfoot>, (default: false)
formats: ["xlsx", "csv", "txt"], // (String[]), filetype(s) for the export, (default: ['xlsx', 'csv', 'txt'])
filename: "id", // (id, String), filename for the downloaded file, (default: 'id')
bootstrap: false, // (Boolean), style buttons using bootstrap, (default: true)
exportButtons: true, // (Boolean), automatically generate the built-in export buttons for each of the specified formats (default: true)
position: "bottom", // (top, bottom), position of the caption element relative to table, (default: 'bottom')
ignoreRows: null, // (Number, Number[]), row indices to exclude from the exported file(s) (default: null)
ignoreCols: null, // (Number, Number[]), column indices to exclude from the exported file(s) (default: null)
trimWhitespace: true, // (Boolean), remove all leading/trailing newlines, spaces, and tabs from cell text in the exported file(s) (default: false)
RTL: false, // (Boolean), set direction of the worksheet to right-to-left (default: false)
sheetname: "id" // (id, String), sheet name for the exported spreadsheet, (default: 'id')
});
Note: to use the
xlsx
filetype, you must include js-xlsx; reference theAdd-Ons
section.
headers
footers
formats
filename
bootstrap
exportButtons
position
ignoreRows
ignoreCols
trimWhitespace
RTL
sheetname
TableExport supports additional methods (getExportData, update, reset and remove) to control the TableExport
instance after creation.
/* First, call the `TableExport` constructor and save the return instance to a variable */
var table = TableExport(document.getElementById("export-buttons-table"));
/* get export data */
var exportData = table.getExportData(); // useful for creating custom export buttons, i.e. when (exportButtons: false)
/*****************
** exportData ***
*****************
{
"export-buttons-table": {
xls: {
data: "...",
fileExtension: ".xls",
filename: "export-buttons-table",
mimeType: "application/vnd.ms-excel"
},
...
}
};
*/
var tableId = "export-buttons-table";
var XLS = table.CONSTANTS.FORMAT.XLS;
/* get export data (see `getExportData` above) */
var exportDataXLS = table.getExportData()[tableId][XLS];
/* get file size (bytes) */
var bytesXLS = table.getFileSize(exportDataXLS.data, exportDataXLS.fileExtension);
/**********************************
** bytesXLS (file size in bytes)
**********************************
352
*/
/* update */
table.update({
filename: "newFile" // pass in a new set of properties
});
/* reset */
table.reset(); // useful for a dynamically altered table
/* remove */
table.remove(); // removes caption and buttons
Below are some of the popular configurable settings to customize the functionality of the library.
/**
* CSS selector or selector[] to exclude/remove cells (<td> or <th>) from the exported file(s).
* @type {selector|selector[]}
* @memberof TableExport.prototype
*/
// selector
TableExport.prototype.ignoreCSS = ".tableexport-ignore";
// selector[]
TableExport.prototype.ignoreCSS = [".tableexport-ignore", ".other-ignore-class"];
// OR using jQuery
// selector
$.fn.tableExport.ignoreCSS = ".tableexport-ignore";
// selector[]
$.fn.tableExport.ignoreCSS = [".tableexport-ignore", ".other-ignore-class"];
/**
* CSS selector or selector[] to replace cells (<td> or <th>) with an empty string in the exported file(s).
* @type {selector|selector[]}
* @memberof TableExport.prototype
*/
// selector
TableExport.prototype.emptyCSS = ".tableexport-empty";
// selector[]
TableExport.prototype.emptyCSS = [".tableexport-empty", ".other-empty-class"];
// OR using jQuery
// selector
$.fn.tableExport.emptyCSS = ".tableexport-empty";
// selector[]
$.fn.tableExport.emptyCSS = [".tableexport-empty", ".other-empty-class"];
/* default charset encoding (UTF-8) */
TableExport.prototype.charset = "charset=utf-8";
/* default `filename` property if "id" attribute is unset */
TableExport.prototype.defaultFilename = "myDownload";
/* default class to style buttons when not using Bootstrap or the built-in export buttons, i.e. when (`bootstrap: false` & `exportButtons: true`) */
TableExport.prototype.defaultButton = "button-default";
/* Bootstrap classes used to style and position the export button, i.e. when (`bootstrap: true` & `exportButtons: true`) */
TableExport.prototype.bootstrapConfig = ["btn", "btn-default", "btn-toolbar"];
/* row delimeter used in all filetypes */
TableExport.prototype.rowDel = "\r\n";
/**
* Format-specific configuration (default class, content, mimeType, etc.)
* @memberof TableExport.prototype
*/
formatConfig: {
/**
* XLSX (Open XML spreadsheet) file extension configuration
* @memberof TableExport.prototype
*/
xlsx: {
defaultClass: 'xlsx',
buttonContent: 'Export to xlsx',
mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
fileExtension: '.xlsx'
},
xlsm: {
defaultClass: 'xlsm',
buttonContent: 'Export to xlsm',
mimeType: 'application/vnd.ms-excel.sheet.macroEnabled.main+xml',
fileExtension: '.xlsm'
},
xlsb: {
defaultClass: 'xlsb',
buttonContent: 'Export to xlsb',
mimeType: 'application/vnd.ms-excel.sheet.binary.macroEnabled.main',
fileExtension: '.xlsb'
},
/**
* XLS (Binary spreadsheet) file extension configuration
* @memberof TableExport.prototype
*/
xls: {
defaultClass: 'xls',
buttonContent: 'Export to xls',
separator: '\t',
mimeType: 'application/vnd.ms-excel',
fileExtension: '.xls',
enforceStrictRFC4180: false
},
/**
* CSV (Comma Separated Values) file extension configuration
* @memberof TableExport.prototype
*/
csv: {
defaultClass: 'csv',
buttonContent: 'Export to csv',
separator: ',',
mimeType: 'text/csv',
fileExtension: '.csv',
enforceStrictRFC4180: true
},
/**
* TXT (Plain Text) file extension configuration
* @memberof TableExport.prototype
*/
txt: {
defaultClass: 'txt',
buttonContent: 'Export to txt',
separator: ' ',
mimeType: 'text/plain',
fileExtension: '.txt',
enforceStrictRFC4180: true
}
},
//////////////////////////////////////////
// Configuration override example
//////////////////////////////////////////
/* Change the CSV (Comma Separated Values) `mimeType` to "application/csv" */
TableExport.prototype.formatConfig.xlsx.mimeType = "application/csv"
TableExport packages with customized Bootstrap CSS stylesheets to deliver enhanced table and button styling. These styles can be enabled by initializing with the bootstrap
property set to true
.
TableExport(document.getElementsByTagName("table"), {
bootstrap: true
});
When used alongside Bootstrap, there are four custom classes .xlsx
, .xls
, .csv
, .txt
providing button styling for each of the exportable filetypes.
Chrome | Firefox | IE | Opera | Safari | |
---|---|---|---|---|---|
Android | ✓ | ✓ | - | ✓ | - |
iOS | ✓ | - | - | - | ✓ |
Mac OSX | ✓ | ✓ | - | ✓ | ✓ |
Windows | ✓ | ✓ | ✓ | ✓ | ✓ |
A full list of browser support can be found in the FileSaver.js README. Some legacy browsers may require an additional third-party dependency: Blob.js
headers
footers
formats
filename
bootstrap
exportButtons
position
ignoreRows
ignoreCols
trimWhitespace
RTL
sheetname
rowspan
colspan
cell data types
(string
,number
,boolean
,date
)emoji
Arabic
- TableExport + RequireJS skeleton.
- TableExport + Flask skeleton.
- TableExport + Webpack 1 skeleton.
- TableExport + Angular 4 + Webpack 2 skeleton.
TableExport is licensed under the terms of the Apache-2.0 License
- Update JSDocs and TypScript definition file.
- Fix bug with CSV and TXT
ignoreRows
andignoreCols
(rows/cols rendered as empty strings rather than being removed). - Reimplement and test the
update
,reset
, andremove
TableExport prototype properties without requiring jQuery. - Make jQuery as peer dependency and ensure proper TableExport rendering in browser, AMD, and CommonJS environments.
- Force jQuery to be an optionally loaded module.
- Use the enhanced SheetJS
xls
,csv
, andtxt
formats (exposed viaenforceStrictRFC4180
prototype property). - Allow
ignoreCSS
andemptyCSS
to work with anyselector|selector[]
instead of solely a single CSS class. - Ensure (via testing) full consistency and backwards-compatibility for jQuery.
- Add Export as PDF support.
Special thanks the the following contributors: