Old Documentation

You are browsing documentation for an old version of Tabulator. Consider upgrading your project to Tabulator 6.3

Column Setup

Overview
Automatic Column Generation
Column Definition
Cell Alignment
Manipulating Columns
Callbacks

Overview

In Tabulator columns are used to define how data loaded into your table should be displayed

Each column should represent a field from the row data that you load into your table, though you do not need a column for each field in your data, only for fields that you want to display in your table.

Columns have a wide variety of configuration options to allow you to customize the table to your usage case.

Automatic Column Generation

If you are building a simple table that only uses strings and numbers for data, and you don't need any interactivity or formatting on the table, then you can get Tabulator to define your columns for you.

If you set the autoColumns option to true, every time data is loaded into the table through the data option or through the setData function, Tabulator will examine the first row of the data and build columns to match that data.

//define data
var tabledata = [
    {id:1, name:"Billy Bob", age:12, gender:"male", height:95, col:"red", dob:"14/05/2010"},
    {id:2, name:"Jenny Jane", age:42, gender:"female", height:142, col:"blue", dob:"30/07/1954"},
    {id:3, name:"Steve McAlistaire", age:35, gender:"male", height:176, col:"green", dob:"04/11/1982"},
];

//define table
var table = new Tabulator("#example-table", {
    data:tabledata,
    autoColumns:true,
});

Tabulator will iterate through each property of the object in the order that they are defined (not alphabetical order), it will use the name of the property as the columns title and will attempt to set the most appropriate sorter for column based on the value of the property (Currently limited to string, number, alphanum, boolean and array).

Column Definition

The column definitions are provided to Tabulator in the columns property of the table constructor object and should take the format of an array of objects, with each object representing the configuration of one column.

var table = new Tabulator("#example-table", {
    columns:[
        {title:"Name", field:"name", sorter:"string", width:200, editor:true},
        {title:"Age", field:"age", sorter:"number", hozAlign:"right", formatter:"progress"},
        {title:"Gender", field:"gender", sorter:"string", cellClick:function(e, cell){console.log("cell click")},},
        {title:"Height", field:"height", formatter:"star", hozAlign:"center", width:100},
        {title:"Favourite Color", field:"col", sorter:"string"},
        {title:"Date Of Birth", field:"dob", sorter:"date", hozAlign:"center"},
        {title:"Cheese Preference", field:"cheese", sorter:"boolean", hozAlign:"center", formatter:"tickCross"},
    ],
});

There are a large number of properties you can choose from to customize your columns:

General

title - Required This is the title that will be displayed in the header for this column
field - Required (not required in icon/button columns) this is the key for this column in the data array
visible - (boolean, default - true) determines if the column is visible. (see Column Visibility for more details)

Layout

hozAlign - sets the horizontal text alignment for this column (left|center|right)
vertAlign - sets the vertical text alignment for this column (top|middle|bottom)
width - sets the width of this column, this can be set in pixels or as a percentage of total table width (if not set the system will determine the best)
minWidth - sets the minimum width of this column, this should be set in pixels (this takes priority over the global option of columnMinWidth)
widthGrow - when using fitColumns layout mode, determines how much the column should grow to fill available space (see Table Layout for more details)
widthShrink - when using fitColumns layout mode, determines how much the column should shrink to fit available space (see Table Layout for more details)
resizable - set whether column can be resized by user dragging its edges (see Table Layout for more details)
frozen - freezes the column in place when scrolling (see Frozen Columns for more details)
responsive - an integer to determine when the column should be hidden in responsive mode (see Responsive Layout for more details)
tooltip - sets the on hover tooltip for each cell in this column (see Formatting Data for more details)
cssClass - sets css classes on header and cells in this column. (value should be a string containing space separated class names)
rowHandle - sets the column as a row handle, allowing it to be used to drag movable rows. (see Movable Rows for more details)
htmlOutput - show or hide column in the getHtml function output (see Retrieve Data as HTML Table for more details)
print - show or hide column in the print output (see Printing for more details)
clipboard - show or hide column in the clipboard output (see Clipboard for more details)

Data Manipulation

sorter - determines how to sort data in this column (see Sorting Data for more details)
sorterParams - additional parameters you can pass to the sorter(see Sorting Data for more details)
formatter - set how you would like the data to be formatted (see Formatting Data for more details)
formatterParams - additional parameters you can pass to the formatter(see Formatting Data for more details)
formatterPrint - set how you would like the data to be formatted when the table is printed(see Formatting Data for more details)
formatterPrintParams - additional parameters you can pass to the print formatter(see Formatting Data for more details)
formatterClipboard - set how you would like the data to be formatted when copied to the clipboard(see Formatting Data for more details)
formatterClipboardParams - additional parameters you can pass to the clipboard formatter(see Formatting Data for more details)
formatterHtmlOutput - set how you would like the data to be formatted when the getHtml function is used(see Formatting Data for more details)
formatterHtmlOutputParams - additional parameters you can pass to the html output formatter(see Formatting Data for more details)
variableHeight -alter the row height to fit the contents of the cell instead of hiding overflow
editable - callback to check if the cell is editable (see Manipulating Data for more details)
editor - set the editor to be used when editing the data. (see Manipulating Data for more details)
editorParams - additional parameters you can pass to the editor (see Manipulating Data for more details)
validator - set the validator to be used to approve data when a user edits a cell. (see Manipulating Data for more details)
contextMenu - add context menu to column cells (see Cell Context Menus for more details)
mutator - function for manipulating column values as they are parsed into the table (see Mutators for more details)
mutatorParams - additional parameters you can pass to the mutator(see Mutators for more details)
mutatorData - function for manipulating column values as they are parsed into the table by command (see Mutators for more details)
mutatorDataParams - additional parameters you can pass to the mutatorData(see Mutators for more details)
mutatorEdit - function for manipulating column values as they are edited by a user (see Mutators for more details)
mutatorEditParams - additional parameters you can pass to the mutatorEdit(see Mutators for more details)
mutatorClipboard - function for manipulating column values as they are pasted by a user (see Mutators for more details)
mutatorClipboardParams - additional parameters you can pass to the mutatorClipboard(see Mutators for more details)
accessor - function to alter column values before they are extracted from the table function (see Accessors for more details)
accessorParams - additional parameters you can pass to the accessor(see Accessors for more details)
accessorData - function to alter column values before they are extracted from the table using the getData function (see Accessors for more details)
accessorDataParams - additional parameters you can pass to the accessorData(see Accessors for more details)
accessorDownload - function to alter column values before they are included in a file download (see Accessors for more details)
accessorDownloadParams - additional parameters you can pass to the accessorDownload(see Accessors for more details)
accessorClipboard - function to alter column values before they are copied to the clipboard (see Accessors for more details)
accessorClipboardParams - additional parameters you can pass to the accessorClipboard(see Accessors for more details)
download - show or hide column in downloaded data (see Downloading Table Data for more details)
downloadTitle - set custom title for column in download (see Downloading Table Data for more details)
topCalc - the column calculation to be displayed at the top of this column(see Column Calculations for more details)
topCalcParams - additional parameters you can pass to the topCalc calculation function (see Column Calculations for more details)
topCalcFormatter - formatter for the topCalc calculation cell (see Column Calculations for more details)
topCalcFormatterParams - additional parameters you can pass to the topCalcFormatter function(see Column Calculations for more details)
bottomCalc - the column calculation to be displayed at the bottom of this column(see Column Calculations for more details)
bottomCalcParams - additional parameters you can pass to the bottomCalc calculation function(see Column Calculations for more details)
bottomCalcFormatter - formatter for the bottomCalc calculation cell (see Column Calculations for more details)
bottomCalcFormatterParams - additional parameters you can pass to the bottomCalcFormatter function(see Column Calculations for more details)

Cell Events

cellClick - callback for when user clicks on a cell in this column (see Callbacks for more details)
cellDblClick - callback for when user double clicks on a cell in this column (see Callbacks for more details)
cellContext - callback for when user right clicks on a cell in this column (see Callbacks for more details)
cellTap - callback for when user taps on a cell in this column, triggered in touch displays. (see Callbacks for more details)
cellDblTap - callback for when user double taps on a cell in this column, triggered in touch displays when a user taps the same cell twice in under 300ms. (see Callbacks for more details)
cellTapHold - callback for when user taps and holds on a cell in this column, triggered in touch displays when a user taps and holds the same cell for 1 second. (see Callbacks for more details)
cellMouseEnter - callback for when the mouse pointer enters a cell (see Callbacks for more details)
cellMouseLeave - callback for when the mouse pointer leaves a cell (see Callbacks for more details)
cellMouseOver - callback for when the mouse pointer enters a cell or one of its child elements(see Callbacks for more details)
cellMouseOut - callback for when the mouse pointer enters a cell or one of its child elements(see Callbacks for more details)
cellMouseMove - callback for when the mouse pointer moves over a cell (see Callbacks for more details)
cellEditing - callback for when a cell in this column is being edited by the user (see Callbacks for more details)
cellEdited - callback for when a cell in this column has been edited by the user (see Callbacks for more details)
cellEditCancelled - callback for when an edit on a cell in this column is aborted by the user (see Callbacks for more details)

Column Headers

headerSort - user can sort by clicking on the header (see Sorting Data for more details)
headerSortStartingDir - set the starting sort direction when a user first clicks on a header (see Sorting Data for more details)
headerSortTristate - allow tristate toggling of column header sort direction (see Sorting Data for more details)
headerClick - callback for when user clicks on the header for this column (see Callbacks for more details)
headerDblClick - callback for when user double clicks on the header for this column (see Callbacks for more details)
headerContext - callback for when user right clicks on the header for this column (see Callbacks for more details)
headerTap - callback for when user taps on a header for this column, triggered in touch displays. (see Callbacks for more details)
headerDblTap - callback for when user double taps on a header for this column, triggered in touch displays when a user taps the same header twice in under 300ms. (see Callbacks for more details)
headerTapHold - callback for when user taps and holds on a header for this column, triggered in touch displays when a user taps and holds the same header for 1 second. (see Callbacks for more details)
headerTooltip - sets the on hover tooltip for the column header (see Formatting Data for more details)
headerVertical - change the orientation of the column header to vertical (see Vertical Column Headers for more details)
editableTitle - allows the user to edit the header titles. (see Editable Column Titles for more details)
titleFormatter - formatter function for header title (see Formatting Data for more details)
titleFormatterParams - additional parameters you can pass to the header title formatter(see Formatting Data for more details)
headerFilter - filtering of columns from elements in the header (see Header Filtering for more details)
headerFilterPlaceholder - placeholder text for the header filter (see Header Filtering for more details)
headerFilterParams - additional parameters you can pass to the header filter (see Header Filtering for more details)
headerFilterEmptyCheck - function to check when the header filter is empty (see Header Filtering for more details)
headerFilterFunc - the filter function that should be used by the header filter (see Header Filtering for more details)
headerFilterFuncParams - additional parameters object passed to the headerFilterFunc function (see Header Filtering for more details)
headerFilterLiveFilter - disable live filtering of the table (see Header Filtering for more details)
headerMenu - add menu button to column header (see Header Menus for more details)
headerContextMenu - add context menu to column header (see Header Context Menus for more details)

Column Grouping

You can group column headers together to create complex multi-row table headers.

To group columns, you need to add a column group object in the column definition array. You must give a column group a title and add the grouped column objects into the columns property of the group.

You can use the columnHeaderVertAlign option to set how the text in your column headers should be vertically aligned, this can take one of three string values: "top", "middle", "bottom"

You can nest column groups, so you can create column groups many levels deep.

var table = new Tabulator("#example-table", {
    columnHeaderVertAlign:"bottom", //align header contents to bottom of cell
    columns:[
        {title:"Name", field:"name", width:160},
        {//create column group
            title:"Work Info",
            columns:[
            {title:"Progress", field:"progress", hozAlign:"right", sorter:"number", width:100},
            {title:"Rating", field:"rating", hozAlign:"center", width:80},
            {title:"Driver", field:"car", hozAlign:"center", width:80},
            ],
        },
        {//create column group
            title:"Personal Info",
            columns:[
            {title:"Gender", field:"gender", width:90},
            {title:"Favourite Color", field:"col", width:140},
            {title:"Date Of Birth", field:"dob", hozAlign:"center", sorter:"date", width:130},
            ],
        },
    ],
});

Available Options

As well as the required title and columns options, the following options can also be set on a column group:

downloadTitle - set custom title for column group in download (see Downloading Table Data for more details)
headerClick - callback for when user clicks on the header for this column group (see Callbacks for more details)
headerDblClick - callback for when user double clicks on the header for this column group (see Callbacks for more details)
headerContext - callback for when user right clicks on the header for this column group (see Callbacks for more details)
cssClass - sets css classes on column group header header. (value should be a string containing space separated class names)
frozen - freezes the column group in place when scrolling (see Frozen Columns for more details)
headerContextMenu - add context menu to column header (see Header Context Menus for more details)

Note: any of the click callbacks on the group header will also be triggered by clicking on any of the column headers in the group. To prevent this from happening put a matching binding on the column header and use the e.stopPropagation() function to prevent the group binding from being triggered.

Handling Nested Data

Tabulator can handle linking columns to fields inside nested data objects. To do this you specify the route to your data using dot notation.

For example here is a basic row data object with data nested inside a user object

{
    id:1,
    user:{
        name:"steve",
        age:23
    },
    col:"red",
    cheese:true
},

If you wanted to make a column that showed the name field inside the user object you could set the field property of the column definition object to user.name

var table = new Tabulator("#example-table", {
    columns:[
        {title:"Name", field:"user.name"},  //link column to name property of user object
    ],
});

Note: This functionality is only available for nested objects and will not work with arrays.

Custom Field Separator

If you need to use the . character as part of your field name, you can change the separator to any other character using the nestedFieldSeparator option

var table = new Tabulator("#example-table", {
    nestedFieldSeparator:"|", //change the field separator character to a pipe
    columns:[
        {title:"Name", field:"user|name"},  //link column to name property of user object
    ],
});

By setting the nestedFieldSeparator to false you can disable nested data parsing. In this case all fields will be assumed to be directly on the row object regardless of characters in the field name

var table = new Tabulator("#example-table", {
    nestedFieldSeparator:false, //disable nested data parsing
});

Vertical Column Headers

By default all column headers have a horizontal text orientation. if you would prefer vertical column headers you can set the headerVertical column definition property to true

{title:"Name", field:"name", headerVertical:true},

The headerVertical property can take one of three values:

false - vertical columns disabled (default value)
true - vertical columns enabled
"flip" - vertical columns enabled, with text direction flipped by 180 degrees

Note: Due to CSS limitations, this option will not work correctly in the Internet Explorer browser.

Cell Alignment

Horizontal Alignment

By default table cells have the same horizontal alignment as the containing element for the table. To change this, you can globally set the horizontal text alignment for all cells in the table using the cellHozAlign option:

var table = new Tabulator("#example-table", {
    cellHozAlign:"center", //center align cell contents
});

The property can take one of three values:

left - left align cell contents
center - center align cell contents
right - right align cell contents

If you want to set the horizontal alignment on a column by column basis, you can use the hozAlign property in a column's definition:

var table = new Tabulator("#example-table", {
    columns:[
        {title:"Name", field:"name", hozAlign:"right"}, //right align column contents
    ],
});

Vertical Alignment

By default table cells are vertically aligned to the top of the cell. To change this, you can globally set the vertical text alignment for all cells in the table using the cellVertAlign option:

var table = new Tabulator("#example-table", {
    cellVertAlign:"middle", //vertically center cell contents
});

The property can take one of three values:

top - align cell contents to the top
middle - align cell contents to the middle
bottom - align cell contents to the bottom

If you want to set the vertical alignment on a column by column basis, you can use the vertAlign property in a column's definition:

var table = new Tabulator("#example-table", {
    columns:[
        {title:"Name", field:"name", vertAlign:"bottom"}, //bottom align column contents
    ],
});

Manipulate Columns

Replace All Column Definitions

To replace the current column definitions for all columns in a table use the setColumns function. This function takes a column definition array as its only argument.

//new column definition array
 var newColumns = [
     {title:"Name", field:"name", sorter:"string", width:200},
     {title:"Age", field:"age", sorter:"number", hozAlign:"right", formatter:"progress"},
     {title:"Height", field:"height", formatter:"star", hozAlign:"center", width:100},
     {title:"Favourite Color", field:"col", sorter:"string"},
     {title:"Date Of Birth", field:"dob", sorter:"date", hozAlign:"center"},
 ],

table.setColumns(newColumns) //overwrite existing columns with new columns definition array

Update A Column Definition

You can update the definition of a column with the updateColumnDefinition function. The first argument can be any any of the standard column component look up options. The second argument should be an object containing the properties of the column that you want to change. Any properties defined on the original column definition and not contained in the update object will be unchanged.

table.updateColumnDefinition("name", {title:"Updated Title"}) //change the title on the name column

Alternatively if you have the Column Component of the column you wish to update, you can call the updateDefinition function directly on the component.

column.updateDefinition({title:"Updated Title"}) //change the column title

New Column Component It is worth noting that using this function actually replaces the old column with a totally new column component, therefor any references to the previous column component will no longer work after this function has been run.

Returned Promise

The updateColumnDefinition and updateDefinition methods return a promise, this can be used to run any other commands that have to be run after the column has been updated. By running them in the promise you ensure they are only run after the table has been redrawn. The promise will resolve with the updated column component for the column as an argument

table.updateColumnDefinition("name", {title:"Updated Title"}) //change the column title
.then(function(column){
    //column - column component for the updated column;
})
.catch(function(error){
    //handle column update error
});

Add Column

If you wish to add a single column to the table, you can do this using the addColumn function.

table.addColumn({title:"Age", field:"age"}, true, "name");

This function takes three arguments:

Columns Definition - The column definition object for the column you want to add.
Before (optional) - Determines how to position the new column. A value of true will insert the column to the left of existing columns, a value of false will insert it to the right. If a Position argument is supplied then this will determine whether the new colum is inserted before or after this column.
Position (optional) - The field to insert the new column next to, this can be any of the standard column component look up options.

Returned Promise

The addColumn method returns a promise, this can be used to run any other commands that have to be run after the column has been added to the table. By running them in the promise you ensure they are only run after the table has loaded the data.

table.addColumn({title:"Name", field:"name"})
.then(function(column){
    //column - the component for the newly created column

    //run code after column has been added
})
.catch(function(error){
    //handle error adding column
});

Delete Column

To permanently remove a column from the table deleteColumn function. This function takes any of the standard column component look up options as its first parameter.

table.deleteColumn("name");

Alternatively if you have the Column Component of the column you wish to delete, you can call the delete function directly on the component.

column.delete();

Returned Promise

The deleteColumn and column.delete methods return a promise, this can be used to run any other commands that have to be run after the column has been deleted. By running them in the promise you ensure they are only run after the column has been deleted.

table.deleteColumn("name")
.then(function(){
    //run code after column has been deleted
})
.catch(function(error){
    //handle error deleting column
});

column.delete()
.then(function(){
    //run code after column has been deleted
})
.catch(function(error){
    //handle error deleting column
});

Get Column Definitions

To get the current column definition array (including any changes made through user actions, such as resizing or re-ordering columns), call the getColumnDefinitions function. this will return the current columns definition array.

var colDefs = table.getColumnDefinitions() //get column definition array

Get Column Component

To get an array of Column Components for the current table setup, call the getColumns function. This will only return actual data columns not column groups.

var cols = table.getColumns() //get array of column components

To get a structured array of Column Components that includes column groups, pass a value of true as an argument.

var cols = table.getColumns(true) //get a structured array of column components

This will return an array of Column Components for the top level columns, whether they are columns or column groups. You can then use the getSubColumns and getParentColumn functions on each component to navigate through the column hierarchy.

Get Component by Field

Using the getColumn function you can retrieve the Column Component using either the field of the column or the DOM node of its header element

var col = table.getColumn("age") //get column component for age column.

Editable Column Titles

Column titles can be made user editable by setting the editableTitle parameter to true in a columns definition object.

{title:"Name", field:"name", editableTitle:true} //allow user to update this columns title

This will result in the columns title being displayed in an input element, that will let the user change the title.

After a the user changes a column title the columnTitleChanged callback is triggered.

var table = new Tabulator("#example-table", {
    columnTitleChanged:function(column){
        //column - the column component for the changed column
    },
});

Column Visibility

Column visibility can be set in a number of different ways.

Column Definition Visibility

You can set the column visibility when you create the column definition array:

{title:"Name", field:"name", visible:false}, //create hidden column for the field "name"

By default columns are set with a visible parameter value of true.

Show Column

You can show a hidden column at any point using the showColumn function. Pass the field name of the column you wish to show as the first parameter of the function.

table.showColumn("name") //show the "name" column

Alternatively if you have the ColumnComponent of the column you wish to show, you can call the show function directly on the component.

column.show();

Hide Column

You can hide a visible column at any point using the hideColumn function. Pass the field name of the column you wish to hide as the first parameter of the function.

table.hideColumn("name") //hide the "name" column

Alternatively if you have the ColumnComponent of the column you wish to hide, you can call the hide function directly on the component.

column.hide();

Toggle Column

You can toggle the visibility of a column at any point using the toggleColumn function. Pass the field name of the column you wish to toggle as the first parameter of the function.

table.toggleColumn("name") ////toggle the visibility of the "name" column

Alternatively if you have the ColumnComponent of the column you wish to toggle, you can call the toggle function directly on the component.

column.toggle();

Column Header Visibility

By setting the headerVisible option to false you can hide the column headers and present the table as a simple list if needed.

var table = new Tabulator("#example-table", {
    headerVisible:false, //hide column headers
});

Callbacks

A range of callbacks are available for columns. See the Column Callbacks section for more information.

Version 6.3 Released!

Column Setup

Overview

Automatic Column Generation Demo

Column Definition

General

Layout

Data Manipulation

Cell Events

Column Headers

Column Grouping Demo

Available Options

Handling Nested Data

Custom Field Separator

Vertical Column Headers

Cell Alignment

Horizontal Alignment

Vertical Alignment

Manipulate Columns

Replace All Column Definitions

Update A Column Definition

Returned Promise

Add Column

Returned Promise

Delete Column

Returned Promise

Get Column Definitions

Get Column Component

Get Component by Field

Editable Column Titles

Column Visibility

Column Definition Visibility

Show Column

Hide Column

Toggle Column

Column Header Visibility Demo

Callbacks

Automatic Column Generation

Column Grouping

Column Header Visibility