Version 6.3 Released!

Click to checkout the new features

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.
dependenciesobject{}Register external table dependencies
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
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
popupContainerboolean, string, elementfalsecontaining element for popups

Columns

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
resizableColumnGuidebooleanfalseShow resize guides when resizing columns
resizableColumnFitbooleanfalseMaintain total column width when resizing a column

Rows

Option Data Type Default Value Description
rowHeaderboolean/objectfalsePass column definition object for row header
rowHeightintegernullSet fixed height for rows
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"
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)
resizableRowGuidebooleanfalseShow resize guides when resizing rows
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
dataSendParamsobject{
"page":"page",
"size":"size",
"sorters":"sorters",
"filters":"filters",
}
Lookup list to link fields expected by the server to their function
dataReceiveParamsobject{
"current_page":"current_page",
"last_page":"last_page",
"data":"data",
}
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
importFileValidatorfunctionvalidate a file before it is imported
importDataValidatorfunctionvalidate the data parsed from a file before it is imported
importHeaderTransformfunctionTransform the value of imported header column titles
importValueTransformfunctionTransform the value of imported cell values
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>

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.
headerSortElement string"<div class='tabulator-arrow'></div>"set the column header sort icon
headerSortClickElement string"header"set which header element triggers a sort when clicked

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

Pagination

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
paginationOutOfRangeinteger, string, functionset the behaviour if a page is loaded outside the max range

Spreadsheet

Option Data Type Default Value Description
spreadsheetbooleanfalseEnable spreadsheet functionality
spreadsheetRowsinteger50The number of rows to include in a blank spreadsheet
registerTableOptioninteger50The number of columns to include in a blank spreadsheet
spreadsheetColumnDefinitionobject{}The column definition used for all columns in the sheet
spreadsheetOutputFullbooleanfalseInclude all data in export, including undefined rows and columns
spreadsheetDataarraynullArray of sheet data
spreadsheetSheetsarraynullArray of sheet definition objects
spreadsheetSheetTabsbooleanfalseShow sheet tabs in footer
spreadsheetSheetTabsElementstring/objectnullAlternate container for sheet tabs element if not using table footer

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

Editing

Option Data Type Default Value Description
editTriggerEventstring"focus"Set which event triggers a cell edit
editorEmptyValueanySet the value assigned to an empty cell after edit
editorEmptyValueFuncfunction(see documentation)Determine what values are considered empty

Selection

Option Data Type Default Value Description
selectableRowsboolean/integer/string"highlight"Enable/Disable row selection
selectableRowsRollingSelectionbooleantrueAllow rolling selection
selectableRowsRangeModestring"drag"Method for selecting multiple rows
selectableRowsPersistencebooleantrueMaintain selected rows on filter or sort
selectableRowsCheckfunction(see documentation)Check if row should be selectable or unselectable
selectableRangeboolean/integerfalseEnable/Disable range selection
selectableRangeColumnsbooleanfalseEnable/Disable range column header selection
selectableRangeClearCellsbooleanfalseEnable clearing of all values in a range
selectableRangeClearCellsValueanyundefinedThe value that cleared range cells should be set to
selectableRangeAutoFocusbooleantrueAuto focus on a cell if the range selection is only one cell

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

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
rowClickMenuarrayfalseAdd left click menu to rows
rowDblClickMenuarrayfalseAdd double left click menu to rows
groupContextMenuarrayfalseAdd context menu to group headers
groupClickMenuarrayfalseAdd left click menu to group headers
groupDblClickMenuarrayfalseAdd double left click menu to group headers

Popups

Option Data Type Default Value Description
rowContextPopupstring, DOM ElementnullAdd context popup to rows
rowClickPopupstring, DOM ElementnullAdd left click popup to rows
rowDblClickPopupstring, DOM ElementnullAdd left click popup to rows
groupContextPopupstring, DOM ElementnullAdd context popup to group headers
groupClickPopupstring, DOM ElementnullAdd left click popup to group headers
groupDblPopupstring, DOM ElementnullAdd left click popup 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.

Donate