Version 6.3 Released!

Click to checkout the new features

User Editing Data

Overview

Tabulator allows for users to edit the data contained in each cell of the table.

Loading Example...
Source Code

HTML

<div id="example-table"></div>

JavaScript

//Create Date Editor
var dateEditor = function(cell, onRendered, success, cancel){
    //cell - the cell component for the editable cell
    //onRendered - function to call when the editor has been rendered
    //success - function to call to pass thesuccessfully updated value to Tabulator
    //cancel - function to call to abort the edit and return to a normal cell

    //create and style input
    var cellValue = luxon.DateTime.fromFormat(cell.getValue(), "dd/MM/yyyy").toFormat("yyyy-MM-dd"),
    input = document.createElement("input");

    input.setAttribute("type", "date");

    input.style.padding = "4px";
    input.style.width = "100%";
    input.style.boxSizing = "border-box";

    input.value = cellValue;

    onRendered(function(){
        input.focus();
        input.style.height = "100%";
    });

    function onChange(){
        if(input.value != cellValue){
            success(luxon.DateTime.fromFormat(input.value, "yyyy-MM-dd").toFormat("dd/MM/yyyy"));
        }else{
            cancel();
        }
    }

    //submit new value on blur or change
    input.addEventListener("blur", onChange);

    //submit new value on enter
    input.addEventListener("keydown", function(e){
        if(e.keyCode == 13){
            onChange();
        }

        if(e.keyCode == 27){
            cancel();
        }
    });

    return input;
};


//Build Tabulator
var table = new Tabulator("#example-table", {
    height:"311px",
    columns:[
        {title:"Name", field:"name", width:150, editor:"input"},
        {title:"Location", field:"location", width:130, editor:"list", editorParams:{autocomplete:"true", allowEmpty:true,listOnEmpty:true, valuesLookup:true}},
        {title:"Progress", field:"progress", sorter:"number", hozAlign:"left", formatter:"progress", width:140, editor:true},
        {title:"Gender", field:"gender", editor:"list", editorParams:{values:{"male":"Male", "female":"Female", "unknown":"Unknown"}}},
        {title:"Rating", field:"rating",  formatter:"star", hozAlign:"center", width:100, editor:true},
        {title:"Date Of Birth", field:"dob", hozAlign:"center", sorter:"date", width:140, editor:dateEditor},
        {title:"Driver", field:"car", hozAlign:"center", editor:true, formatter:"tickCross"},
    ],
});

Columns of the table can be set as editable using the editor property in the column definition. (see Define Columns for more details).

When a user clicks on an editable column the will be able to edit the value for that cell.

By default Tabulator will use an editor that matches the current formatter for that cell. if you wish to specify a specific editor, you can set them per column using the editor option in the column definition. Passing a value of true to this option will result in Tabulator applying the editor that best matches the columns formatter, if present.

You can pass an optional additional parameter with the editor, editorParams that should contain an object with additional information for configuring the editor.

{title:"Rating", field:"rating", editor:"star", editorParams:{stars:4}}

Params Lookup Function

If you want to dynamically generate the editorParams at the time the editor is called you can pass a function into the property that should return the params object.

//define lookup function
function paramLookup(cell){
    //cell - the cell component

    //do some processing and return the param object
    return {param1:"green"};
}

//column definition
{title:"Rating", field:"rating", editor:"star", editorParams:paramLookup}

Built In Editors

Tabulator comes with a number of built-in editors including:

Note: For a guide to adding your own editors to this list, have a look at the Extending Tabulator section.

Input

The input editor allows entering of a single line of plain text

{title:"Example", field:"example", editor:"input", editorParams:{
    search:true,
    mask:"AAA-999",
    selectContents:true,
    elementAttributes:{
        maxlength:"10", //set the maximum character length of the input element to 10 characters
    }
}}

The editor has optional properties for the editorParams object:

  • search - use search type input element with clear button
  • mask - apply a mask to the input to allow characters to be entered only in a certain order (see Text Input Masking for more information
  • selectContents - when the editor is loaded select its text content
  • elementAttributes - set attributes directly on the input element

Text Area

The textarea editor allows entering of multiple lines of plain text

{title:"Example", field:"example", editor:"textarea", editorParams:{
    elementAttributes:{
        maxlength:"10", //set the maximum character length of the textarea element to 10 characters
    },
    mask:"AAA-999",
    selectContents:true,
    verticalNavigation:"editor", //navigate cursor around text area without leaving the cell
    shiftEnterSubmit:true, //submit cell value on shift enter
}}

The editor has optional properties for the editorParams object:

  • elementAttributes - set attributes directly on the textarea element
  • mask - apply a mask to the input to allow characters to be entered only in a certain order (see Text Input Masking for more information
  • selectContents - when the editor is loaded select its text content
  • verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take three different types of value:
    • hybrid - the arrow keys move the cursor around the text area, when the cursor reaches the start or end of the contents of the text area it navigates to the next row of the table (default)
    • editor - the arrow keys move the cursor around the textarea contents but do not navigate round the table
    • table - the arrow keys will navigate to the prev/next row and will not move the cursor in the editor
  • shiftEnterSubmit - submit the cell value when the shift and enter keys are pressed

Numeric

The number editor allows for numeric entry with a number type input element with increment and decrement buttons.

{title:"Example", field:"example", editor:"number", editorParams:{
    min:0,
    max:100,
    step:10,
    elementAttributes:{
        maxlength:"10", //set the maximum character length of the input element to 10 characters
    },
    mask:"999",
     selectContents:true,
    verticalNavigation:"table", //up and down arrow keys navigate away from cell without changing value
}}

The editor has optional properties for the editorParams object:

  • max - the maximum allowed value
  • min - the minimum allowed value
  • step - the step size when incrementing/decrementing the value (default 1)
  • elementAttributes - set attributes directly on the input element
  • mask - apply a mask to the input to allow characters to be entered only in a certain order (see Text Input Masking for more information
  • selectContents - when the editor is loaded select its text content
  • verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take two different types of value:
    • editor - the arrow keys increase/decrease the value in the editor and do not navigate the table(default)
    • table - the arrow keys will navigate to the prev/next row and will not affect the cell value

Range

The range editor allows for numeric entry with a range type input element.

{title:"Example", field:"example", editor:"range", editorParams:{
    min:0,
    max:100,
    step:10,
    elementAttributes:{
        maxlength:"10", //set the maximum character length of the input element to 10 characters
    }
}}

The editor has optional properties for the editorParams object:

  • max - the maximum allowed value
  • min - the minimum allowed value
  • step - the step size when incrementing/decrementing the value (default 1)
  • elementAttributes - set attributes directly on the input element

Checkbox

The tickCross editor allows for boolean values using a checkbox type input element.

{title:"Example", field:"example", editor:"tickCross", editorParams:{
    trueValue:"car",
    falseValue:"bike",
    tristate:true,
    indeterminateValue:"n/a",
    elementAttributes:{
        maxlength:"10", //set the maximum character length of the input element to 10 characters
    }
}}

The editor has optional properties for the editorParams object:

  • trueValue - The value returned from the editor when the checkbox is ticked (leave undefined for standard boolean values)
  • falseValue - The value returned from the editor when the checkbox is unticked (leave undefined for standard boolean values)
  • tristate - allow tristate tickbox (default false)
  • indeterminateValue - when using tristate tickbox what value should the third indeterminate state have (default null)
  • elementAttributes - set attributes directly on the input element

Star Rating

The star editor allows entering of numeric value using a star rating indicator.

This editor will automatically detect the correct number of stars to use if it is used on the same column as the star formatter.

Users can use left/right arrow keys and enter for selection as well as the mouse.

{title:"Example", field:"example", editor:"star", editorParams:{
    elementAttributes:{
        maxlength:"10", //set the maximum character length of the input element to 10 characters
    }
}}

The editor has optional properties for the editorParams object:

  • elementAttributes - set attributes directly on the star holder element

Progress Bar

The progress editor allows adjusting a numeric value formatted using the progress formatter.

This editor will automatically detect maximum and minimum values of the progress bar from the formatter, or they can be manually overriden in the editorParams.

{title:"Example", field:"example", editor:"progress", editorParams:{
    min:7, // the minimum value of the progress bar
    max:46, // the maximum value of the progress bar
    elementAttributes:{
        title:"slide bar to choose option" // custom tooltip
    }
}}

The editor has optional properties for the editorParams object:

  • min - the minimum value for the progress bar
  • max - the maximum value for the progress bar
  • elementAttributes - set attributes directly on the progress holder element

Date

Dependency Required
If you use the format param with this editor, you will need to include the luxon.js library to perform the format conversion. The Dependencies Docs contain info on how to register other libraries with Tabulator.

The date editor allows for editing of a date using a standard date type input field.

{title:"Example", field:"example", editor:"date", editorParams:{
    min:"01/01/2020", // the minimum allowed value for the date picker
    max:"02/12/2022", // the maximum allowed value for the date picker
    format:"dd/MM/yyyy", // the format of the date value stored in the cell
    verticalNavigation:"table", //navigate cursor around table without changing the value
    elementAttributes:{
        title:"slide bar to choose option" // custom tooltip
    }
}}

The editor has optional properties for the editorParams object:

  • min - the earliest day available for the date picker, the default format is yyyy-mm-dd, if the format param is used then it will expect the date in that format instead
  • max - the latest day available for the date picker, the default is yyyy-mm-dd, if the format param is used then it will expect the date in that format instead
  • format - the format for the date to be stored in the table. This accepts any valid Luxon format string, or the value "iso" which accept any ISO formatted data. If the input value is a luxon DateTime object then you should set this option to true. If this value param is ignored then the data should be in the format YYYY-MM-DD(this will not affect the format the user has to enter the data into the table, that is determined by the browser)
  • verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take three different types of value:
    • editor - the arrow keys increment/decrement the selected value but will not navigate round the table (default)
    • table - the arrow keys will navigate to the prev/next row and will not move the cursor in the editor
  • elementAttributes - set attributes directly on the progress holder element

Browser Styling
Because this editor uses the default date type input element, it is up to each browser to choose how the date picker will function and be styled, which may lead to an inconsistent look and feel. If you need consistent functionality across browsers then it recomended that you make a custom editor using an external date picker library.

Advanced Functionality
This intended as a simple date picker, if you are looking for advanced functionality then it is recomended that you build a custom editor using an external date picker library.

Time

Dependency Required
If you use the format param with this editor, you will need to include the luxon.js library to perform the format conversion. The Dependencies Docs contain info on how to register other libraries with Tabulator.

The time editor allows for editing of a time using a standard time type input field.

{title:"Example", field:"example", editor:"time", editorParams:{
    format:"hh:mm:ss", // the format of the time value stored in the cell
    verticalNavigation:"table", //navigate cursor around table without changing the value
    elementAttributes:{
        title:"slide bar to choose option" // custom tooltip
    }
}}

The editor has optional properties for the editorParams object:

  • format - the format for the time to be stored in the table. This accepts any valid Luxon format string, or the value "iso" which accept any ISO formatted data. If the input value is a luxon DateTime object then you should set this option to true. If this value param is ignored then the data should be in the format hh:mm(this will not affect the format the user has to enter the data into the table, that is determined by the browser)
  • verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take three different types of value:
    • editor - the arrow keys increment/decrement the selected value but will not navigate round the table (default)
    • table - the arrow keys will navigate to the prev/next row and will not move the cursor in the editor
  • elementAttributes - set attributes directly on the progress holder element
< class="note"> Browser Styling
Because this editor uses the default time type input element, it is up to each browser to choose how the time picker will function and be styled, which may lead to an inconsistent look and feel. If you need consistent functionality across browsers then it recomended that you make a custom editor using an external time picker library.

Advanced Functionality
This intended as a simple time picker, if you are looking for advanced functionality then it is recomended that you build a custom editor using an external time picker library.

Date Time

Dependency Required
If you use the format param with this editor, you will need to include the luxon.js library to perform the format conversion. The Dependencies Docs contain info on how to register other libraries with Tabulator.
Compatibility Warning
This editor uses the datetime-local type input element, which is not currently fully supported by the Firefox browser

The datetime editor allows for editing of a date and time using a standard datetime type input field.

{title:"Example", field:"example", editor:"datetime", editorParams:{
    format:"dd/MM/yyyy hh:mm", // the format of the date value stored in the cell
    verticalNavigation:"table", //navigate cursor around table without changing the value
    elementAttributes:{
        title:"slide bar to choose option" // custom tooltip
    }
}}

The editor has optional properties for the editorParams object:

  • format - the format for the date-time to be stored in the table. This accepts any valid Luxon format string, or the value "iso" which accept any ISO formatted data. If the input value is a luxon DateTime object then you should set this option to true. If this value param is ignored then the data should be in the format YYYY-MM-DDThh:mm(this will not affect the format the user has to enter the data into the table, that is determined by the browser)
  • verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take three different types of value:
    • editor - the arrow keys increment/decrement the selected value but will not navigate round the table (default)
    • table - the arrow keys will navigate to the prev/next row and will not move the cursor in the editor
  • elementAttributes - set attributes directly on the progress holder element
< class="note"> Browser Styling
Because this editor uses the default datetime-local type input element, it is up to each browser to choose how the date-time picker will function and be styled, which may lead to an inconsistent look and feel. If you need consistent functionality across browsers then it recomended that you make a custom editor using an external date-time picker library.

Advanced Functionality
This intended as a simple date-time picker, if you are looking for advanced functionality then it is recomended that you build a custom editor using an external date-time picker library.

List (Select/Autocomplete)

The list editor creates a dropdown list to allow the user to select from some predefined options, by default it functions as a select list type element but can also be configured to function as an autocomplete.

{title:"Example", field:"example", editor:"list", editorParams:{
    //Value Options (You should use ONE of these per editor)
    values:["red", "green", "blue", "orange"], //an array of values or value/label objects
    valuesURL: "http://myvalues.com", //a url to load the values from
    valuesLookup:"active", //get the values from the currently active rows in this column

    //Value Lookup Configuration (use these with valuesLookup Option)
    valuesLookupField:"color", //the field to lookup values from

    //General Options
    clearable:true, //show clear "x" button on editpr
    itemFormatter:function(label, value, item, element){
        //label - the text lable for the item
        //value - the value for the item
        //item - the original value object for the item
        //element - the DOM element for the item

        return "<strong>" + label + " </strong><br/><div>" + item.subtitle + "</div>";
    },
    elementAttributes:{ //set attributes on input element
        maxlength:"10", //set the maximum character length of the input element to 10 characters
    },
    verticalNavigation:"hybrid", //navigate to new row when at the top or bottom of the selection list
    sort:"asc", //sort direction for the values list
    defaultValue:"Steve Johnson", //the value that should be selected by default if the cells value is undefined
    emptyValue:null, //the value that should be asigned to the cell if the editor is left with an empty value
    maxWidth:true, //prevent width of list item from exceeding width of cell
    placeholderLoading:"Loading List...", //set custom placeholder when loading list values
    placeholderEmpty:"No Results Found", set custom placeholder when list is empty

    //Select Options (only available when autocomplete:false)
    multiselect:true, //allow selection of multiple items from the list

    //Autocomplete Options (only available when autocomplete:true)
    autocomplete:true, //enable autocomplete mode,
    filterFunc:function(term, label, value, item){ //replace built in filter function with custom
        //term - the string being searched for
        //label - the text lable for the item
        //value - the value for the item
        //item - the original value object for the item

        return label === term;
    },
    filterRemote:true, //pass filter term to remote server in request instead of filtering
    filterDelay:100, //delay in milliseconds after typing before filter begins
    allowEmpty:true, //allow the user to leave the cell empty
    listOnEmpty:true, //show all values in the list if the input is empty
    mask:"AAA-999", //apply input mask to text entry
    freetext:true, //allow the user to set the value of the cell to a free text entry
}}

The editor has many optional properties for the editorParams object:

  • values - either an array of values, or value objects (this is explained in more detail in the next section)
  • valuesURL - the url to load the values for the list from
  • valuesLookup - lookup the values for the list from a column in the table, this option sets which range of data should be loaded, or provides a function to dynamically set the data
  • valuesLookupField - the field the values for this list should be looked up from
  • clearable - adds a clear button to the right of the editor to allow the user to empty the current value
  • itemFormatter - change how the items in the list are displayed
  • elementAttributes - set attributes directly on the input element
  • verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take three different types of value:
    • editor - value selection up and down the list, will not navigate round the table (default)
    • table - the arrow keys will navigate to the prev/next row and will not change the selected value in the list
    • hybrid - the arrow keys move the value selection up and down the list, when it reaches the end of the list it moves on to the adjacent row
  • sort - sort the items in the list, either asc or desc or a custom sorter function
  • defaultValue - set the value that should be selected by default if the cells value is undefined
  • emptyValue - set the value that will be set on the cell if the user leave the input empty
  • maxWidth - the list will by default expand to fit the contents of the list, if you wish to constrain the width of the list, you can either pass an integer for the maximum width of the list in pixels, or the value true which will fit the list to the width of the current cell
  • placeholderLoading - set custom placeholder when loading list values, this can either be a text string, a valid HTML string a DOM Element, or a function, that will be called and passed in the cell component and the current list element and should return one of the above valid placeholder values.
  • placeholderEmpty - set custom placeholder when list is empty, this can either be a text string, a valid HTML string a DOM Element, or a function, that will be called and passed in the cell component and the current list element and should return one of the above valid placeholder values.
  • multiselect - set this to true to allow the user to choose multiple values. With this option enabled the editor will accept and return an array of values. (this option is only available when the autocomplete option is disabled)
  • autocomplete - set this to true to allow the user to filter the options list by typing in the input.
  • filterFunc - a custom filter function to define how an autocomplete should filter its row values. (this option is only available when the autocomplete option is enabled)
  • filterRemote - When using a remote data source like Ajax, this tells hte auto complete to submit the search term as part of the request instead of triggering a local filter function. (this option is only available when the autocomplete option is enabled)
  • filterDelay - The delay in milliseconds between a person typing a letter and the filter begginging, used to delay filtering until the user has finished typing. (default value 300 - this option is only available when the autocomplete option is enabled)
  • allowEmpty - allow the user to save an empty value to the cell. (this option is only available when the autocomplete option is enabled)
  • listOnEmpty - show the whole list of values when the cell is empty. (this option is only available when the autocomplete option is enabled)
  • mask - apply a mask to the input to allow characters to be entered only in a certain order (this option is only available when the autocomplete option is enabled) (see Text Input Masking for more information)
  • freetext - allow the user to press enter to save a value to the cell that is not in the list (this option is only available when the autocomplete option is enabled)

Values

There are multiple ways you can define the values in list depending on your needs, the sections below outline each detail

Values - Array / Object

You can pass in an array of values to the vaulues param:

{title:"Example", field:"example", editor:"list", editorParams:{values:["red", "green", "blue", "orange"]}}

In this mode, the value will also be used as the label for the list item.

If you want to show a different label to the value you want to store, you can pass in an object, where the key of each property is the value that will be stored if it is selected, and the value of each property will be the label displayed for it in the list.

{title:"Name", field:"name", editor:"list", editorParams:{
    values:{
        "steve":"Steve Boberson",
        "bob":"Bob Jimmerson",
        "jim":"Jim Stevenson",
    }
}}

You can alternativly pass an array of value objects, each with a value and label object, if you would like to specify a different label for each value and their order. You can also add custom properties to each of the objects that will be accessible in the sort, filter and layout functions if you want to use other data in your list

With an aray of value objects, you can also create groups of options using the options property on an item and passing an array of value objects to the prop.

In the complex structure you can also use the elementAttributes property to define attributes directly on the list item element

{title:"Name", field:"name", editor:"select", editorParams:{
    values:[
        {
            label:"Steve Boberson",
            value:"steve",
            keywords:"red, green, blue, orange", // custom field
            description:"Likes to drive a car", // custom field
        },
        { //option group
            label:"Men",
            options:[ //options in option group
                {
                    label:"Steve Boberson",
                    value:"steve",
                    elementAttributes:{
                        class:"primary-name",
                    }
                },
                {
                    label:"Bob Jimmerson",
                    value:"bob",
                },
            ]
        },
        { //option group
            label:"Women",
            options:[ //options in option group
                {
                    label:"Jenny Jillerson",
                    value:"jenny",
                },
                {
                    label:"Jill Betterson",
                    value:"jill",
                },
            ]
        },
        {//ungrouped option
            label:"Other",
            value:"other",
        },
    ]
}}

Values - Lookup From Column

Using the valuesLookup option cause the editor to lookup the unique values from a column on the table.

When using the valuesLookup option, it is used to specify the range of rows that shoul be used for the lookup, and takes any of the standardRow Range Lookup.

It should be used in conjunction with the valuesLookupField option in which you can set the field name for the column you want to lookup the data from.

{title:"Name", field:"name", editor:"list", editorParams:{
    valuesLookup:true,  //lookup all unique values
    valuesLookupField:"people", //lookup all unique values from the people column
}}

If you leave out the valuesLookupField option it will lookup the values from the current column:

{title:"Name", field:"name", editor:"list", editorParams:{
    valuesLookup:"active",  //lookup filtered unique values in this column
}}

Alternativly if you want to generate the content in a different way, you can pass a callback to the valuesLookup option that should return a value array or object. The callback is passed in the Cell Component for the cell being edited, and the currenty value of the input in case you are using the filterRemote option.

{title:"Name", field:"name", editor:"list", editorParams:{
    valuesLookup:function(cell, filterTerm){
        //cell - the cell component for the current cell
        //filterTerm - the current value of the input element

        return [
            {
                label:"Steve Boberson",
                value:"steve",
            },
            {
                label:"Bob Jimmerson",
                value:"bob",
            },
            {
                label:"Jenny Jillerson",
                value:"jenny",
            },
            {
                label:"Jill Betterson",
                value:"jill",
            },
        ];
    }
}}

If you want to carry out an asynchronous function in this callback, like a custom ajax request, then you can return a promise from this function that should resolve with the value array / object.

Values - Remote Ajax Source

If you want to lookup data from a remote ajax source, you can get the table to make a simple AJAX get request to a url by passing it to the valuesURL option.

If you are also using filterRemote then the current value of the input element will aslo be passed in the request as the term parameter.

The request should respond with a JSON encoded values array/object.

{title:"Name", field:"name", editor:"list", editorParams:{
    valuesURL:"http://getdata.fromhere.com",  //get value list from URL
}}

The valuesURL option is only intended for a simple GET ajax request. If you need to make a different/more complex request, then you should use the valuesLookup option and make the ajax request yourself.

While making the request, a placeholder element will be displayed to the user, the contents of this placeholder can be set using the placeholderLoading option. This can either be a text string, valid HTML, a DOM node or a callback function that will return one of those options. If you use a callback function, the first argument will be the Cell Component for the cell being edited.

{title:"Name", field:"name", editor:"list", editorParams:{
    valuesURL:"http://getdata.fromhere.com",  //get value list from URL
    placeholderLoading:"Loading Remote Data...", //set a custom placeholder text
}}

Formatting List

By default, Tabulator will render the values list as a simple list of text values. You can choose to format the list in any way you like, using the itemFormatter option.

This option takes a callback that will be called for each item in the list, it will be passed in the value of the item the first argument, the label for the item as the second argument, the original value object for the component as its third argument, complete with any custom properties that may have been set and the containing element for the list item as the fourth argument incase you wish to directly manipulate it by applying classes etc.

The callback return a text string, valid HTML, or a DOM node for the contents of the item.

{title:"Name", field:"name", editor:"list", editorParams:{
    itemFormatter:function(label, value, item, element){
        //label - the text lable for the item
        //value - the value for the item
        //item - the original value object for the item
        //element - the DOM element for the item

        //return the initial label as a bold line and then second line in regular font weight containing the value of the custom "subtitle" prop set on the value item object.
        return "<strong>" + label + " </strong><br/><div>" + item.subtitle + "</div>";
    },
}}

Sorting List

By default no sort will be applied to the values list. it will appear in the order the items were defined. You can sort the list using the sort option, this can take the string value of asc to sort the list in ascending order by label, or the string value of desc to sort the list in descending order by label.

{title:"Name", field:"name", editor:"list", editorParams:{
    sort:"asc", //sort list in ascending order
}}

By default, Tabulator uses an alphanumeric sort on list values. If you would like to apply a custom sort to the list, then you can also pass a callback function into this option. This callback will function in the same way as the comparison function passed to the standard JavaScript sort function, it should return -1 if value "a" is less than value "b", 1 if it is greater than, and 0 if they are equal.

The function is passed in several arguments:

{title:"Name", field:"name", editor:"list", editorParams:{
    sort:(aLabel, bLabel, aValue, bValue, aItem, bItem){
        //aLabel - the text lable for item a
        //bLabel - the text lable for item b
        //aValue - the value for item a
        //bValue - the value for item b
        //aItem - the original value object for item a
        //bItem - the original value object for item b

        
        //sort by numeric values
        return aValue < bValue ? -1 : (aValue == bValue ? 0 : 1);
    },
}}

Filtering List

When using the editor with autocomplete enabled, the list will be filtered every time the user types in the input. By default this is accomplished using a case-insensitive string comparison between the value of the input element and the label of the list item.

If you wish to filter in a different way, you can pass a callback to the filterFunc option. This option is passed four aguments, the term being searched for, the label of the item, the value of the item, and the item object. It should return true if the item matches the term and false if it does not

{title:"Name", field:"name", editor:"list", editorParams:{
    filterFunc:(term, label, value, item){
        //term - the string value from the input element
        //label - the text lable for the item
        //value - the value for the item
        //item - the original value object for the item

        //filter strictly against the value of the item
        return term === value;
    },
}}

If you are retreiving your data from a remote source using either the valueURL option, or a promise return from a callback on the valuesLookup option, then you can choose to filter your data remotely instead and bypass the local filter.

This can be accomplished using the filterRemote option. With this enabled, the local filter will not be run, instead the remote request will be retriggered with the current search term pass as an argument.

{title:"Name", field:"name", editor:"list", editorParams:{
    valuesURL:"http://getdata.fromhere.com",  //get value list from URL
    filterRemote:true,
}}

Adaptable

The adaptable editor is a bit of a special case, instead of creating an editor itself, it lets you pick between any existing editor based on the value of the cell. This is particularly useful when a column might have varying types of data that you may need each cell to be editied differently.

{title:"Example", field:"example", editor:"adaptable"}

By default the adaptable editor will attempt to pick an editor based on the cells value:

  • Number - If the value is a number type, the number editor will be used
  • Boolean - If the value is a boolean type, the tickCross editor will be used
  • Text - If the value is a string with a carriage return in it, the textarea editor will be used
  • Input - for all other values, the input editor will be used

Note This editor should not be used as a header filter, as header filters have no initial value, it will always default to an input editor if used in this way.

Customise Editor Lookup

You can customise which editors are chosen using the editorLookup option on the editorParams object. This option takes a function with one argument, the CellComponent for the cell being edited. The function should return the choice of editor, this can be any value that can be passed to the normal editor option

{title:"Example", field:"example", editor:"adaptable", editorParams:{
    editorLookup:function(cell){
        //cell - the Cell Component for the cell being edited
        
        var value = cell.getValue();
        
        return Array.isArray(value) ? "list" : "input"; // if the cell contains an array, use the list editor, otherwise use the input editor;
    }
}}

Params Lookup

You can also customise the params that are passed into the chosen editor by using the paramsLookup option on the editorParams object. You should pass an object into this option, with a key for each type of editor that can be looked up, and a value of ts params object:

{title:"Example", field:"example", editor:"adaptable", editorParams:{
    paramsLookup:{
        "input":{
            mask:"AAA-999",
        },
        "number":{
            min:0,
            max:100,
            step:10
        }
    }
}}

Alternatively, if you need more control of the params generated for the editor, you can pass a function into the paramsLookup option. This function takes two arguments, the first ist the editor that has been chosen, the second is the CellComponent for the cell being edited. The function should return the params object for that editor:

{title:"Example", field:"example", editor:"adaptable", editorParams:{
    paramsLookup:(lookup, cell) => {
        return {
            max: cell.getColumn().getField() === "age" ? 100 : 999, //set the max value on the age number editor to 100 and let all other columns use 999
        };
    }
}}

Custom Editors

If you need a different type of editor, you can pass a custom editor function to the editor option. This function should take five arguments, a CellComponent for the cell being edited, a function to call when the cell has ben rendered, which can be used to set focus or tidy up the display after the element has become visible, a function to call to pass back the new value, when the user hassuccessfully entered new data in the cell, a function to call if the user aborts the edit and parameters passed in from the editorParams column definition property.

The Custom editor function should return a DOM Node for the editor that will be inserted into the cell. or a value of false to abort the edit.

var dateEditor = function(cell, onRendered, success, cancel, editorParams){
    //cell - the cell component for the editable cell
    //onRendered - function to call when the editor has been rendered
    //success - function to call to pass thesuccessfully updated value to Tabulator
    //cancel - function to call to abort the edit and return to a normal cell
    //editorParams - params object passed into the editorParams column definition property

    //create and style editor
    var editor = document.createElement("input");

    editor.setAttribute("type", "date");

    //create and style input
    editor.style.padding = "3px";
    editor.style.width = "100%";
    editor.style.boxSizing = "border-box";

    //Set value of editor to the current value of the cell
    editor.value = luxon.DateTime.fromFormat(cell.getValue(), "dd/MM/yyyy").toFormat("yyyy-MM-dd")

    //set focus on the select box when the editor is selected (timeout allows for editor to be added to DOM)
    onRendered(function(){
        editor.focus();
        editor.style.css = "100%";
    });

    //when the value has been set, trigger the cell to update
    function successFunc(){
        success(luxon.DateTime.fromFormat(cell.getValue(), "yyyy-MM-dd").toFormat("dd/MM/yyyy"));
    }

    editor.addEventListener("change", successFunc);
    editor.addEventListener("blur", successFunc);

    //return the editor element
    return editor;
};


//in your column definition for the column
{title:"Birthday", field:"dob", editor:dateEditor}}

Blur Event
It is important to note that a custom editor must specify how to handle a blur event on its element by either calling the success or cancel functions. This is because when a user clicks or tabs out of a cell, the blur event will be fired and must be handled to move on to the next cell. As a fallback Tabulator will cancel the edit if an editor is blured and the event has not been correctly handled.

Optional Editing

There are some circumstances where you may want to block editability of a cell for one reason or another. To meet this need you can use the editable option. This lets you set a callback that is executed before the editor is built, if this callback returns true the editor is added, if it returns false the edit is aborted and the cell remains a non editable cell. The function is passed one parameter, the CellComponent of the cell about to be edited. You can also pass a boolean value instead of a function to this property.

var editCheck = function(cell){
    //cell - the cell component for the editable cell

    //get row data
    var data = cell.getRow().getData();

    return data.age > 18; // only allow the name cell to be edited if the age is over 18
}

//in your column definition for the column
{title:"Name", field:"name", editor:"input", editable:editCheck}

Data Mutation
if you have defined any mutator functions in your column definition array, these will be applied to your edited value as it is being parsed into the table. (see Mutators for more details)

Trigger Event

The editTriggerEvent option lets you choose which type of interaction event will trigger an edit on a cell.

var table = new Tabulator("#example-table", {
    editTriggerEvent:"dblclick", //trigger edit on double click
});

This option can take one of three values:

  • focus - trigger edit when the cell has focus (default)
  • click - trigger edit on single click on cell
  • dblclick - trigger edit on double click on cell

This option does not affect navigation behavior, cells edits will still be triggered when they are navigated to through arrow keys or tabs.

Text Input Masking

Built in editors based on input elements such as the input, number, textarea and autocomplete editors have the ability to mask the users input to restrict it to match a given pattern.

This can be set by passing a string to the the mask option in the columns editorParams

{title:"Name", field:"name", editor:"input", editorParams:{mask:"AAA-999"}}

Each character in the string passed to the mask option defines what type of character can be entered in that position in the editor.

  • A - Only a letter is valid in this position
  • 9 - Only a number is valid in this position
  • * - Any character is valid in this position
  • Any other character - The character in this position must be the same as the mask

For example, a mask string of "AAA-999" would require the user to enter three letters followed by a hyphen followed by three numbers

Autofill Fixed Characters

If you are using fixed characters in your mask (any character other that A, 9 or *), then you can get the mask to automatically fill in these characters for you as you type by setting the maskAutoFill option in the editorParams to true

{title:"Name", field:"name", editor:"input", editorParams:{
    mask:"AAA-999",
    maskAutoFill:true,
}}

Custom Pattern Characters

If you want to use the characters A, 9 or * as fixed characters then it is possible to change the characters looked for in the mask by using the maskLetterChar, maskNumberChar and maskWildcardChar options in the editorParams

{title:"Name", field:"name", editor:"input", editorParams:{
    mask:"A!!-9BBB$",
    maskLetterChar:"B",
    maskNumberChar:"!",
    maskWildcardChar:"$",
}}

In the example the above the input would be masked with the first character being "A" followed by two numbers, followed by a hyphen, followed by the number "9", followed by three numbers, followed by any character

Empty Values

When editing a cell, if a user clears the value of the cell and then leaves focus the value of the cell is often set to an empty string "" or other similarly empty value. This is not always a desierable option, you may want to ensure that empty cells always have the same value, for example a value of undefined.

For this reason the editorEmptyValue option lets you set what value should be assigned to a cell when it is edited and the value is empty.

Tabulator considers an edit to be empty when the value is either:

  • An empty string
  • null
  • undefined

The editorEmptyValue option can either be set on the table as a whole to affect all columns.

var table = new Tabulator("#example-table", {
    editorEmptyValue:undefined, //set empty cell values to undefined after edit
});

Or on a column definition alongside an editor:

{title:"Name", field:"name", editor:"input", editorEmptyValue:undefined}

If neither of these options are set, then the empty cell will be asigned the value returned from the editor.

Empty Value Classification

As mentioned above, Tabulator will consider a very specific list of values to be empty, you can customise this behaviour using the editorEmptyValueFunc option, that lets you define custom callback logic to determine what is classed as empty.

You should pass a callback to this option that takes the edited value as its first argument, it should return a value of true if the value should be considered empty:

var table = new Tabulator("#example-table", {
    editorEmptyValue:undefined, //set empty cell values to undefined after edit
    editorEmptyValueFunc:(value) =>{ 
        return value === ""; //only consider empty strings as empty
    },
});

This can also be set on a column by column basis in the column definition:

{title:"Name", field:"name", editor:"input", editorEmptyValue:undefined, editorEmptyValueFunc:(value) =>{ 
    return value === ""; //only consider empty strings as empty
}}

Edit History

Whenever a cell is edited a flag is set to mark that cell as edited

List Edited Cells

You can get a list of all edited cells in the table using the getEditedCells function. this will return an array of Cell Components for each cell that has been edited.

var editedCells = table.getEditedCells()

Tabulator will continue to add cells to this list until the table in the data is replaced by the setData function or the edited list is cleared.

Check if Cell Has Been Edited

You can call the isEdited function on any Cell Component to see if it has been edited. it will return true if it has been edited or false if it has not.

var edited = cell.isEdited()

Clear Edited Cells

You can clear the edited flag on a cell to prevent ir from coming up in edited lists in future

The clearEdited can be called on a Cell Component to clear the edited flag used by the isEdited function and mark the cell as unedited.

cell.clearEdited();

Alternativly, the clearCellEdited can be called on the table to clear the edited flag on all cells in the table

table.clearCellEdited();

Or optionally you can pass in a Cell Component or an array of Cell Components to the clearCellEdited function to clear the edited flag on specific cells

table.clearCellEdited([cell1, cell2]);

Events

A range of events are available for table editing. See the Edit Events section for more information.

Donate