Version 6.3 Released!

Click to checkout the new features

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

Setup Options

Overview

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.
virtualDombooleantrueEnable/disable rendering using the Virtual DOM engine
virtualDomBufferintegerfalseManually set the size of the virtual DOM buffer
placeholderstring/DOM Node""placeholder element to display on empty table
footerElementstring/DOM Node(see documentation)Footer element for the table
tooltipsboolean/functionfalseFunction to generate tooltips for cells
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
downloadDataFormatterfunctionfalsecallback function to alter table data before download
downloadConfigobjectobjectchoose which parts of the table are included in downloaded files
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
invalidOptionWarningsbooleantrueshow console warnings if invalid options are used

Columns

Option Data Type Default Value Description
columnsarray[]Holder for column definition array
autoColumnsbooleanfalseAutomatically generate column definitions for the table based on the structure of the first row of data
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
cellHozAlignstring"left"horizontal alignment for cell contents
cellVertAlignstring"top"vertical alignment for cell contents
columnMinWidthCSS width value40pxMinimum width for a column
resizableColumnsbooleantrueAllow user to resize columns (via handles on the left and right edges of the column header)
movableColumnsbooleanfalseAllow users to move and reorder columns
tooltipsHeaderboolean/functionfalseFunction to generate tooltips for column headers
columnHeaderVertAlignstringtopVertical alignment for contents of column header (used in column grouping)
headerFilterPlaceholderstring"filter column..."The placeholder text to be set in any header filter input elements
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

Rows

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

Data

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
ajaxFilteringbooleanfalseSend filter config to server instead of processing locally
ajaxSortingbooleanfalseSend sorter config to server instead of processing locally
ajaxProgressiveLoadbooleanfalseProgressively load data into the table in chunks
ajaxProgressiveLoadDelayinteger0Delay in milliseconds between each progressive load request
ajaxProgressiveLoadScrollMarginintegerfalseThe remaining distance in pixels between the scroll bar and the bottom of the table before an ajax is triggered
ajaxLoaderboolean/functiontrueShow loader while data is loading, can also take a function that must return a boolean
ajaxLoaderLoadingstringhtml (see below)html for loader element
ajaxLoaderErrorstringhtml (see below)html for the loader element 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>

Sorting

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.
headerSortbooleantrueEnable or disable header sorting on all columns.
headerSortTristatebooleanfalseEnable or disable tristate header sorting on all columns.

Filtering

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

Pagination

Option Data Type Default Value Description
paginationstringfalseChoose pagination method, "local" or "remote"
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
paginationDataReceivedobject{
"current_page":"current_page",
"last_page":"last_page",
"data":"data",
}
Lookup list to link expected data fields from the server to their function
paginationDataSentobject{
"page":"page",
"size":"size",
"sorters":"sorters",
"filters":"filters",
}
Lookup list to link fields expected by the server to their function
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
persistenceIDstringnullID tag used to identify persistent storage information
persistenceModeboolean/stringtrueStore persistence information in a cookie or localStorage
persistentLayoutbooleanfalseEnable persistsnt storage of column layout information
persistentSortbooleanfalseEnable persistsnt storage of sorting information
persistentFilterbooleanfalseEnable persistsnt storage of filtering information

Clipboard

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

Printing

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

Menus

Option Data Type Default Value Description
rowContextMenuarrayfalseAdd context menu to rows

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 prototype 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.prototype.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

Donate