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).
Customising Automatic Column Definitions
By default, columns generated using the autoColumns option will be basic columns with no additional configuration. If you want to customize the column definitions for these columns then you can use the autoColumnsDefinitions option to manipulate the generated column definition array.
The autoColumnsDefinitions option can be used in three different ways.
Callback Function
If you pass a function to the autoColumnsDefinitions option, it will be called when the column definitions have been generated. It will be passed the column definition array for you to manipulate. The callback must return the array of definition objects.
var table = new Tabulator("#example-table", { data:tabledata, autoColumns:true, autoColumnsDefinitions:function(definitions){ //definitions - array of column definition objects definitions.forEach((column) => { column.headerFilter = true; // add header filter to every column }); return definitions; }, });
Column Definition Array
If you pass an array of column definition objects to the autoColumnsDefinitions option, the properties for each object will be copied over to the generated column definitions.
Objects are matched by field, so you must set the fieldproperty for each object in the array.
var table = new Tabulator("#example-table", { data:tabledata, autoColumns:true, autoColumnsDefinitions:[ {field:"name", editor:"input"}, //add input editor to the name column {field:"age", headerFilter:true}, //add header filters to the age column ], });
Definitions will only be applied to columns generated by autocolums, others will be ignored. So you can use this to define options for possible columns, that will only be included if they are needed.
Field Name Lookup Object
If you pass an object to the autoColumnsDefinitions option, it will lookup the definitions for each column, with the field name of the column used as the property name in the object
var table = new Tabulator("#example-table", { data:tabledata, autoColumns:true, autoColumnsDefinitions:{ name: {editor:"input"}, //add input editor to the name column age: {headerFilter:true}, //add header filters to the age column }, });
Definitions will only be applied to columns generated by autocolums, others will be ignored. So you can use this to define options for possible columns, that will only be included if they are needed.
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)
- headerHozAlign - sets the horizontal text alignment for this columns header title (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)
- 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)
- clicktMenu - add left click 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)
- headerMenu - add menu button to column header for this column group (see Header Menus 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 ], });
Column Header Title Alignment
By default column headers are left aligned. To change this, you can globally set the horizontal text alignment for all cells in the table using the headerHozAlign option:
var table = new Tabulator("#example-table", { headerHozAlign:"right", //right align column header titles });
The property can take one of three values:
- left - left align column header title
- center - center align column header title
- right - right align column header title
If you want to set the horizontal alignment on a column by column basis, you can use the headerHozAlign property in a column's definition:
var table = new Tabulator("#example-table", { columns:[ {title:"Name", field:"name", headerHozAlign:"right"}, //right align column header title ], });
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.