Old Documentation

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

Column Setup

Overview
Column Definition
- Column Grouping
- Handling Nested Data
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.

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", align:"right", formatter:"progress"},
        {title:"Gender", field:"gender", sorter:"string", cellClick:function(e, cell){console.log("cell click")},},
        {title:"Height", field:"height", formatter:"star", align:"center", width:100},
        {title:"Favourite Color", field:"col", sorter:"string"},
        {title:"Date Of Birth", field:"dob", sorter:"date", align:"center"},
        {title:"Cheese Preference", field:"cheese", sorter:"boolean", align:"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

align - sets the text alignment for this column (left|center|right)
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)
hideInHtml - When the getHtml function is called, hide the column from the output.

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)
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)
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)
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)
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)
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)

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 columnVertAlign 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", {
    columnVertAlign:"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", align:"right", sorter:"number", width:100},
            {title:"Rating", field:"rating", align:"center", width:80},
            {title:"Driver", field:"car", align:"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", align:"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:

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)

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.

Manipulate Columns

Replace Column Definitions

To replace the current column definitions for 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", align:"right", formatter:"progress"},
 {title:"Height", field:"height", formatter:"star", align:"center", width:100},
 {title:"Favourite Color", field:"col", sorter:"string"},
 {title:"Date Of Birth", field:"dob", sorter:"date", align:"center"},
 ],

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

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.

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();

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();

Callbacks

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

Version 6.3 Released!

Column Setup

Overview

Column Definition

General

Layout

Data Manipulation

Cell Events

Column Headers

Column Grouping Demo

Available Options

Handling Nested Data

Manipulate Columns

Replace Column Definitions

Add Column

Delete Column

Get Column Definitions

Get Column Component

Get Component by Field

Editable Column Titles

Column Visibility

Column Definition Visibility

Show Column

Hide Column

Toggle Column

Callbacks

Column Grouping