Version 6.3 Released!

Click to checkout the new features
Old Documentation
You are browsing documentation for an old version of Tabulator. Consider upgrading your project to Tabulator 6.3

Download Table Data

Overview

Tabulator allows you to download/export the table data as a file directly from your browser, no server needed.

The download will contain the text values of all data currently visible in the table, matching the current column layout, column titles, sorting and filtering.

Download Controls
Loading Example...
Source Code

XLSX Script Includes

<script type="text/javascript" src="https://oss.sheetjs.com/sheetjs/xlsx.full.min.js"></script>

PDF Script Includes

<script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/1.3.5/jspdf.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf-autotable/3.0.5/jspdf.plugin.autotable.js"></script>

HTML

<div id="example-table"></div>

JavaScript

//Build Tabulator
var table = new Tabulator("#example-table", {
    height:"311px",
    columns:[
        {title:"Name", field:"name", width:200},
        {title:"Progress", field:"progress", width:100, sorter:"number"},
        {title:"Gender", field:"gender"},
        {title:"Rating", field:"rating", width:80},
        {title:"Favourite Color", field:"col"},
        {title:"Date Of Birth", field:"dob", align:"center", sorter:"date"},
        {title:"Driver", field:"car", align:"center", formatter:"tickCross"},
    ],
});

//trigger download of data.csv file
$("#download-csv").click(function(){
    table.download("csv", "data.csv");
});

//trigger download of data.json file
$("#download-json").click(function(){
    table.download("json", "data.json");
});

//trigger download of data.xlsx file
$("#download-xlsx").click(function(){
    table.download("xlsx", "data.xlsx", {sheetName:"My Data"});
});

//trigger download of data.pdf file
$("#download-pdf").click(function(){
    table.download("pdf", "data.pdf", {
        orientation:"portrait", //set page orientation to portrait
        title:"Example Report", //add title to report
    });
});

//trigger download of data.html file
$("#download-html").click(function(){
    table.download("html", "data.html", {style:true});
});

You have a choice of four file types to choose from:

To trigger a download, call the download function, passing the file type (from the above list) as the first argument, and an optional second argument of the file name for the download (if this is left out it will be "Tabulator.ext"). The optional third argument is an object containing any setup options for the formatter, such as the delimiter choice for CSV's).

table.download("csv", "data.csv"); //download table data as a CSV formatted file with a file name of data.csv

Download Data Set

By default the download function will include only the active rows in the download output (those that match the current filters). The optional fourth argument to the download function allows you to specify the data set you wish to download, you can choose from one of three options:

  • active - include the active (filtered) rows only in the download output (default)
  • all - include all rows in the download output regardless of whether they are filtered or not
  • visible - include only rows currently visible in the table viewport
table.download("csv", "data.csv", {}, "visible"); //include only rows visible in the table viewport in the download output

Grouped Data
The all option is not available for grouped data. This is because grouping is carried out after filtering in Tabulators data processing pipeline, so only filtered data ever makes it into groups.

Download To New Browser Tab

If you want to open the generated file in a new browser tab rather than downloading it straight away, you can use the downloadToTab function. This is particularly useful with the PDF downloader, as it allows you to preview the resulting PDF in a new browser tab

table.downloadToTab("pdf"); //convert table to PDF and open in new tab

Tabulator has no control over how browsers handle the opening of files in new browser tabs, depending on the browser and its configuration some files may open smoothly in a new tab, others may trigger a download prompt.

CSV Download

Config Options
The CSV downloader does not support grouped column headers, row groups or column calculations, because of the limited way to representing these in CSV data

Custom CSV Delimiters

By default CSV files are created using a comma (,) delimiter. If you need to change this for any reason the you can pass the options object with a delimiter property to the download function which will then use this delimiter instead of the comma.

table.download("csv", "data.csv", {delimiter:"."}); //download a CSV file that uses a fullstop (.) delimiter

Byte Order Mark

If you need the output CSV to include a byte order mark (BOM) to ensure that output with UTF-8 characters can be correctly interpreted across different applications, you should set the bom option to true

table.download("csv", "data.csv", {bom:true}); //include BOM in output

XLSX Download

The XLSX downloader requires that the SheetJS Library be included on your site, this can be included with the following script tag.

<script type="text/javascript" src="https://oss.sheetjs.com/sheetjs/xlsx.full.min.js"></script>

Sheet Name

You can set the name of the sheet in the xlsx download, using the sheetName property in the options object

table.download("xlsx", "data.xlsx", {sheetName:"MyData"}); //download a xlsx file that has a sheet name of "MyData"

Valid Characters
The sheet name must be a valid Excel sheet name, and cannot include any of the following characters \, /, *, [, ], :, ?

SheetJS Options

You can configure the workbook using the native SheetJS workbook setup options with the optional documentProcessingcallback. This function is called when the workbook is ready to be created. The first argument is the workbook object complete with all the sheet data. It must return the updated workbook

table.download("xlsx", "data.xlsx",{
    documentProcessing:function(workbook){
        //workbook - sheetJS workbook object

        //set some properties on the workbook file
        workbook.Props = {
            Title: "SheetJS Tutorial",
            Subject: "Test",
            CreatedDate: new Date(2017,12,19)
        };

        return workbook;
    }
}); //download a xlsx file using SheetJS properties

Multi Table Download

You can pull the data from multiple Tabulators into one xlsx file, using the sheets property of the options object.

This accepts an object, with the keys of each property being the sheet name, and the values being the tables to draw the data from, this can either be a string representing the query selector, or a DOM Node. If you pass a value of true it will use the current table. The order of the keys determines the order of the sheets

var sheets = {
    "Accounts Data": "#accounts-table", //first tab with table set using a query selector
    "Example Data": true, //second tab, generated from this table
    "Finance Data" : financeTable, //third tab with table set to DOM Node
};

table.download("xlsx", "AllData.xlsx", {sheets:sheets}); //download a Xlsx file that has a tab for each table

PDF Download

The PDF downloader requires that the jsPDF Library and jsPDF-AutoTable Plugin be included on your site, this can be included with the following script tags.

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/1.3.5/jspdf.min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jspdf-autotable/3.0.5/jspdf.plugin.autotable.js"></script>

UTF-8 Support
The autotable plugin does not currently fully support UTF-8 with its built-in fonts. This Git Hub Issue contains a workaround for adding UTF-8 enabled fonts if needed

Setup Options

There are a number of options you can pass into the PDF downloader to configure the output

  • orientation - the orientation of the page, either portrait or landscape (default value of landscape)
  • title - optional page title
  • rowGroupStyles - style object for row group headers if used (if you want to override the default styling), it can take any of the standard Autotable style options
  • rowCalcStyles - style object for column calculation rows if used (if you want to override the default styling), it can take any of the standard Autotable style options
  • jsPDF - an optional object that will be passed into the jsPDF constructor and can take any of the standard jsPDF options
  • autoTable - an optional object that can be used to configure advanced styling on the table if needed, this can take ay of the standard AutoTable options
  • documentProcessing - an optional callback that is passed the jsPDF document object after the auto-table creation to allow full customisation of the PDF, see the jsPDF document for a full list of methods that can be called on this object
table.download("pdf", "data.pdf", {
    orientation:"portrait", //set page orientation to portrait
    title:"Dynamics Quotation Report", //add title to report
    jsPDF:{
        unit:"in", //set units to inches
    },
    autoTable:{ //advanced table styling
        styles: {
            fillColor: [100, 255, 255]
        },
        columnStyles: {
            id: {fillColor: 255}
        },
        margin: {top: 60},
    },
    documentProcessing:function(doc){
        //carry out an action on the doc object
    }
});

AutoTable Function

You can also pass a function into the autoTable property, this should return the autoTable config object. The jsPDF document object will be passed in as the first argument of this function which will allow you to call any of the jsPDF API functions on the document, so you can for example add additional text to your PDF or set the font.

table.download("pdf", "data.pdf", {
    orientation:"portrait", //set page orientation to portrait
    autoTable:function(doc){
        //doc - the jsPDF document object

        //add some text to the top left corner of the PDF
        doc.text("SOME TEXT", 1, 1);

        //return the autoTable config options object
        return {
            styles: {
                fillColor: [200, 00, 00]
            },
        };
    },
});

Custom File Formatter

If you want to create a custom file type from the table data then you can pass a function to the type argument, instead of a string value. At the end of this function you must call the setFileContents function, passing the formatted data and the mime type.

//custom file formatter
var fileFormatter = function(columns, data, options, setFileContents){
    //columns - column definition array for table (with columns in current visible order);
    //data - currently displayed table data
    //options - the options object passed from the download function
    //setFileContents - function to call to pass the formatted data to the downloader

    //create a list of all name fields
    var names = [];

    data.forEach(function(row){
        names.push(row.name);
    });

    //trigger file download, passing the formatted data and mime type
    setFileContents(names.join(", "), "text/plain");
}

//trigger file download
table.download(fileFormatter, "test.txt");

Note: You can find out more about data URI's Here.

HTML Download

Styling

By default the HTML output is a simple unstyled table. if you would like to match the current table styling you can set the style property to true in the options object

table.download("html", "data.html", {style:true}); //download a html table with matching styling

Advanced Options

Download Configuration

By default Tabulator includes column headers, row groups and column calculations in the download output.

You can choose to remove column headers groups, row groups or column calculations from the output data by setting the values in the downloadConfig option in the table definition:

var table = new Tabulator("#example-table", {
    downloadConfig:{
        columnGroups:false, //include column groups in column headers for download
        rowGroups:false, //do not include row groups in download
        columnCalcs:false, //do not include column calculation rows in download
    },
});

Availabilitity
Not all downloaders support column header groups, row groups and column calculations, see the documentation for each downloader for full information.

Include Hidden Column in Download

By default hidden columns are not included in the download, If you want to force a particular column to show in the download, even if it is hidden, you can set the download property in its column definition object to true:

var table = new Tabulator("#example-table", {
    columns:[
        {title:"id", field:"id", visible:false, download:true} //force hidden field to show in download
    ]
});

Hide Column In Download

If you don't want to show a particular column in the downloaded data you can set the download property in its column definition object to false:

var table = new Tabulator("#example-table", {
    columns:[
    {title:"Hidden Column", field:"secret", download:false} //hide data in download
    ]
});

Change Column Title in Download

You can add a custom column title to be used in the downloaded data instead of the usual title by setting the downloadTitle property in the column definition object:

var table = new Tabulator("#example-table", {
    columns:[
    {title:"Name", field:"name", downloadTitle:"Full Name"} //change column title to "Full Name" in download
    ]
});

Download Accessors

You can use the accessorDownload and accessorDownloadParams options on a column definition to alter the value of data in a column before it is added to the download.

The example below will transform all ages into a boolean, showing if they are over 18 or not. The accessorDownloadParams is used to pass the age limit to the accessor so the same accessor function can be used on multiple columns with different age limits:

var ageAccessor = function(value, data, type, params, column){
    return value >= params.legalAge;
}

{title:"Under Age", field:"age", accessorDownload:ageAccessor, accessorDownloadParams:{legalAge:18} }

Full details of how accessors work can be found in the Accessors Documentation.

Format Data Before Download

If you want to make any bulk changes to the table data before it is parsed into the download file you can pass a mutator function to the downloadDataFormatter option in the table definition.

In the example below we map the numerical age column into a string of "adult" or "child" based on the age value

var table = new Tabulator("#example-table", {
    downloadDataFormatter:function(data){
    //data - active table data array

    //change data

    //return data for download
    return data;
}
});

This callback is called after the column accessors are applied.

Intercept & Manipulate Download Blob

The downloadReady callback allows you to intercept the download file data before the users is prompted to save the file.

In order for the download to proceed the downloadReady callback is expected to return a blob of file to be downloaded.

If you would prefer to abort the download you can return false from this callback. This could be useful for example if you want to send the created file to a server via ajax rather than allowing the user to download the file.

var table = new Tabulator("#example-table", {
    downloadReady:function(fileContents, blob){
    //fileContents - the unencoded contents of the file
    //blob - the blob object for the download

    //custom action to send blob to server could be included here

    return blob; //must return a blob to proceed with the download, return false to abort download
}
});

Callbacks

A range of callbacks are available for downloads. See the Download Callbacks section for more information.

Donate