Version 6.2 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.2

Setup Options


Tabulator has a wide range of setup options to help you customise the user experience of your tables. This section outlines all the available options and links to the relevant section in this documentation to show you how to use them.

Each of these options can be set in the constructor object when you define your Tabulator.

var table = new Tabulator("#example-table", {
    height:"300px", //set the table height option

General Table Configuration

Option Data Type Default Value Description
heightstring/intfalseSets the height of the containing element, can be set to any valid height css value. If set to false (the default), the height of the table will resize to fit the table data.
minHeightstring/intfalseSets the minimum height for the table, can be set to any valid height css value.
maxHeightstring/intfalseSets the maximum height for the table, can be set to any valid height css value.
renderVerticalstring"virtual"Set the tables vertical renderer
renderVerticalBufferintegerfalseManually set the size of the vertical renderer buffer
renderHorizontalstring"basic"Set the tables horizontal renderer
placeholderstring/DOM Node""placeholder element to display on empty table
footerElementstring/DOM Node(see documentation)Footer element for the table
tooltipGenerationModestring"load"When to regenerate cell tooltip value
historyboolean/functionfalseEnable user interaction history functionality
keybindingsboolean/functionfalseKeybinding configuration object
localestring/booleanfalseset the current localization language
langsobject(see documentation)hold localization templates
downloadConfigobjectobjectchoose which parts of the table are included in downloaded files
downloadRowRangestring"active"set the range of rows to be included in the downloaded table output
htmlOutputConfigobjectobjectchoose which parts of the table are included in getHtml function output
reactiveDatabooleanfalseenable data reactivity
tabEndNewRowboolean/object/functionfalseadd new row when user tabs of the end of the table
validationModestring"blocking"set validation mode of the table
textDirectionstring"auto"set text direction for the table
debugInvalidOptionsbooleantrueshow console warnings if invalid options are used


Option Data Type Default Value Description
columnsarray[]Holder for column definition array
columnDefaultsobject{}define any default options that should be applied to all columns
autoColumnsbooleanfalseAutomatically generate column definitions for the table based on the structure of the first row of data
autoColumnsDefinitionsfunction/array/objectfalseManipulate the automatically generated column definitions
layoutstring"fitData"Layout mode for the table columns
layoutColumnsOnNewDatabooleanfalseChange column widths to match data when loaded into table
responsiveLayoutbooleanfalseAutomatically hide/show columns to fit the width of the Tabulator element
responsiveLayoutCollapseStartOpenbooleantrueshow collapsed column list
responsiveLayoutCollapseUseFormattersbooleantrueuse formatters in collapsed column lists
responsiveLayoutCollapseFormatterfunctioncreate contents of collapsed column list
movableColumnsbooleanfalseAllow users to move and reorder columns
columnHeaderVertAlignstringtopVertical alignment for contents of column header (used in column grouping)
scrollToColumnPositionstring"left"Default column position after scrollToColumn
scrollToColumnIfVisiblebooleanfalseAllow currently visible columns to be scrolled to
columnCalcsstring/booleantrueWhere to show column calcs in table
nestedFieldSeparatorstring/boolean"."Character used to separate nested fields in column definition
headerVisiblebooleantrueDisable column header bar


Option Data Type Default Value Description
rowFormatterfunction/booleanfalseFunction to alter layout of rows
rowFormatterPrintfunction/booleannullFunction to alter layout of rows when printed
rowFormatterClipboardfunction/booleannullFunction to alter layout of rows when copied to the clipboard
rowFormatterHtmlOutputfunction/booleannullFunction to alter layout of rows when the getHtml formatter is called
addRowPosstring"bottom"The position in the table for new rows to be added, "bottom" or "top"
selectableboolean/integer/string"highlight"Enable/Disable row selection
selectableRollingSelectionbooleantrueAllow rolling selection
selectablePersistencebooleantrueMaintain selected rows on filter or sort
selectableCheckfunction(see documentation)Check if row should be selectable or unselectable
movableRowsbooleanfalseAllow users to move and reorder rows
movableRowsConnectedTablesstring/DOM NodefalseConnection selector for receiving tables
movableRowsSenderstring/function/booleanfalseSender function to be executed when row has been sent
movableRowsReceiverstring/function"insert"Sender function to be executed when row has been received
movableRowsConnectedElementsstring/DOM NodefalseConnection selector for receiving elements
movableRowsElementDropfunctionfalseCallback executed when a table row is dropped on a non Tabulator DOM element
resizableRowsbooleanfalseAllow user to resize rows (via handles on the top and bottom edges of the row)
scrollToRowPositionstring"top"Default row position after scrollToRow
scrollToRowIfVisiblebooleanfalseAllow currently visible rows to be scrolled to


Option Data Type Default Value Description
indexstringidThe field to be used as the unique index for each row
dataarray[]Array to hold data that should be loaded on table creation
ajaxURLstring/booleanfalseURL for remote Ajax data loading
ajaxParamsobject{}Parameters to be passed to remote Ajax data loading request
ajaxConfigstring/object"GET"The HTTP request type for Ajax requests or config object for the request
ajaxContentTypestring/object"form"set the content encoding for the json request
ajaxURLGeneratorfunctionfalsecallback function to generate request URL
ajaxRequestFuncfunctionfalsecallback function to replace inbuilt ajax request functionality
Lookup list to link fields expected by the server to their function
Lookup list to link expected data fields from the server to their function
filterModestring"local"Send filter config to server instead of processing locally
sortModestring"local"Send sorter config to server instead of processing locally
progressiveLoadbooleanfalseProgressively load data into the table in chunks
progressiveLoadDelayinteger0Delay in milliseconds between each progressive load request
progressiveLoadScrollMarginintegerfalseThe remaining distance in pixels between the scroll bar and the bottom of the table before an ajax is triggered
importFormatstring/functionThe importer for the incoming table data
importReaderstring"text"The type of file reader to be used to import a dataset from a file
dataLoaderboolean/functiontrueShow loader while data is loading, can also take a function that must return a boolean
dataLoaderLoadingstringhtml (see below)html for loader element
dataLoaderErrorstringhtml (see below)html for the loader element in the event of an error
dataLoaderErrorTimeoutinteger3000The number of milliseconds to display the loader error message in the event of an error

When loading data, Tabulator can display a loading overlay over the table. This consists of a modal background and a loader element. The loader element can be set globally in the options and should be specified as a div with a display style of inline-block.

Default loader element

<div style='display:inline-block; border:4px solid #333; border-radius:10px; background:#fff; font-weight:bold; font-size:16px; color:#000; padding:10px 20px;'>Loading Data</div>

Default loader error element

<div style='display:inline-block; border:4px solid #D00; border-radius:10px; background:#fff; font-weight:bold; font-size:16px; color:#590000; padding:10px 20px;'>Loading Error</div>


You can set initial sorters, specifying what sort should be applied when data is first loaded into the table.

Option Data Type Default Value Description
initialSortarray[]Array of sorters to be applied on load.
sortOrderReversebooleanfalseReverse the order that multiple sorters are applied to the table.
headerSortElement string"<div class='tabulator-arrow'></div>"set the column header sort icon


You can set initial filters to be applied to the table.

Option Data Type Default Value Description
initialFilterarray[]Array of filters to be applied on load.
initialHeaderFilterarray[]Array of initial values for header filters.
headerFilterLiveFilterDelayinteger300Number of milliseconds to wait after a keystroke before triggering a header filter.

Row Grouping

Option Data Type Default Value Description
groupBystring/function/arrayfalseString/function to select field to group rows by
groupValuesarrayfalseArray of values for groups
groupHeaderfunction/array(see documentation)function to layout group header row
groupHeaderPrintfunction/arraynullFunction to alter layout of group header rows when printed
groupHeaderClipboardfunction/arraynullFunction to alter layout of group header rows when copied to the clipboard
groupHeaderDownloadfunction/arraynullFunction to alter layout of group header rows when downloaded
groupHeaderHtmlOutputfunction/arraynullFunction to alter layout of group header rows when the getHtml formatter is called
groupStartOpenboolean/function/arraytrueBoolean/function to set the open/closed state of groups when they are first created
groupToggleElementstring/boolean"arrow"Set which element triggers a group visibility toggle
groupClosedShowCalcsbooleanfalseshow/hide column calculations when group is closed


Option Data Type Default Value Description
paginationstringfalseenable pagination
paginationModestring"local"Send pagination config to server instead of processing locally
paginationSizeinteger10Set the number of rows in each page
paginationSizeSelectorboolean/arrayfalseAdd page size selection select element to the table footer
paginationElementDOM Node(generated tabulator footer)The element to contain the pagination selectors
paginationAddRowstring"page"Set where rows should be added to the table
paginationButtonCountinteger5set the number of pagination buttons in the footer element

Persistent Configuration

Option Data Type Default Value Description
persistenceboolean/objectfalseDefine which table data should be persisted
persistenceIDstringnullID tag used to identify persistent storage information
persistenceModeboolean/stringtrueStore persistence information in a cookie or localStorage
persistenceReaderFuncfunctionnullOverride persistence reader functionality to read from custom package
persistenceWriterFuncfunctionnullOverride persistence writer functionality to write to custom package


Option Data Type Default Value Description
clipboardbooleanfalseEnable clipboard module
clipboardCopyRowRangestring/function"active"Set which rows are visible in clipboard output
clipboardCopyFormatterfunctionfalseFormat clipboard output before it is inserted in the clipboard
clipboardPasteParserstring/functionfalseClipboard paste parser function
clipboardPasteActionstring/functionfalseClipboard paste action function

Data Tree

Option Data Type Default Value Description
dataTreebooleanfalseEnable tree layout
dataTreeFilterbooleantrueEnable filtering of child rows
dataTreeSortbooleantrueEnable sorting of child rows
dataTreeElementColumnstring/booleanfalseChoose which column to display the toggle element in
dataTreeBranchElementbooleantrueShow tree branch icon
dataTreeChildIndentinteger9Tree level indent in pixels
dataTreeChildFieldstring"_children"The data field to look for child rows
dataTreeCollapseElementboolean/string/DOM ElementfalseThe element to be used for the collapse toggle button
dataTreeExpandElementboolean/string/DOM ElementfalseThe element to be used for the expand toggle button
dataTreeStartExpandedboolean/array/functionfalseThe default expansion state for tree nodes
dataTreeSelectPropagatebooleanfalseAllow selection of a row to propagate to its children
dataTreeChildColumnCalcsbooleanfalseInclude visible child rows in column calculations


Option Data Type Default Value Description
printAsHtmlbooleanfalseEnable HTML table printing
printStyledbooleanfalseCopy table style to html print table
printRowRangestring"visible"set the range of rows to be included in the printed table output
printConfigobjectobjectChoose which parts of the table are included in print table
printHeaderboolean/string/DOM Element/functionfalseAdd header to printed table
printFooterboolean/string/DOM Element/functionfalseAdd footer to printed table
printFormatterfunction/booleanfalseAlter layout of print elements


Option Data Type Default Value Description
rowContextMenuarrayfalseAdd context menu to rows
rowClickMenuarrayfalseAdd left click menu to rows
groupContextMenuarrayfalseAdd context menu to group headers
groupClickMenuarrayfalseAdd left click menu to group headers

Finding Tables

When you first create a table, the constructor function returns the instance of that table to a variable:

var table = new Tabulator("#example-table", {
    height:"300px", //set the table height option

Sometimes you may want to access this table but not have easy access to the variable that the table was stored in.

The good news is that Tabulator keeps track of all tables that it creates and you can use the findTable function on the Tabulator class to lookup the table object for any existing table using the element they were created on.

The findTable function will accept a valid CSS selector string or a DOM node for the table as its first argument.

var table = Tabulator.findTable("#example-table")[0]; // find table object for table with id of example-table

The findTable function will return an array of matching tables. If no match is found it will return false

Default Options

If you pass the same setup options to your Tabulator constructor object into every table you build on a page, then you can simplify your table setup process by setting these globally for all tables.

You can do this by setting the options on the defaultOptions object on the Tabulator class, these will then automatically apply to any new Tabulator's unless the value is overwritten in a specific tables construction object when you create a new table.

For example the below code will cause all Tabulators to have movable rows by default and set the layout mode to fitColumns.

Tabulator.defaultOptions.movableRows = true;
Tabulator.defaultOptions.layout = "fitColumns";

These options must be set on Tabulator after it has been included in your project but before any tables are instantiated.

Overriding Default Options

If you define an option in your defaultOptions object then it is possible to override it on a specific table by including the replacement for that option in the table constructor:

//Set Default option for all tables
Tabulator.defaultOptions.layout = "fitColumns";

//Override default option in a specific table
var table = new Tabulator("#example-table", {
    layout:"fitData", //override specific default option

Object Properties
It is worth noting that any option defined in a table will completely replace the default option. If you are using an object or array as the value for the property you are overriding, it will not merge the values of each property of the object, it will completely replace the default object with the new one defined in your table.