Columns Configuration

Columns configuration is specified by parameter columns and all settings are managed on its level.

    columns:[{...}, {...}],

With the help of the columns parameter you can:

Automatic Column Configuration

Normally, you need to specify an array of column configurations for the datatable, which allows setting various parameters for each column:

    {id:"id", header:"Id", width:50, sort:"int"},
    {id:"title", header:[ "Film title",{content:"textFilter"}]

At the same time, you can switch to the data-based column configuration provided by the autoConfig property:


In this case the columns array is no longer needed. Datatable will analyze the dataset passed to it and build columns automatically. The columns will have default settings:

  • sort:"string" (columns that begin with $- are not included; these columns are helper fields, e.g. $css, $count);
  • editor:"text" (works only if editable:true in the datatable configuration);
  • fillspace:true for the first column, width:100 for the rest;
  • select:"row" (unless other setting is passed in the datatable configuration)


The header and footer are enabled by the parameters header and footer, correspondingly (by default, headers are enabled).

The values of the attributes header and footer can be both string and object. In case of string, you can put into the header text labels, images, HTML inputs, and links. See the details in the related section.

The object definition allows you to specify a more complex column presentation. As an object, a header/footer can contain the following properties:

  • text - the text label of a column;
  • colspan - the number of columns a cell should span;
  • rowspan - the number of rows a cell should span;
  • content - the built-in filter of a column (textFilter, selectFilter or any other from the list of filters);
  • tooltip - the tooltip for cells of the column, more details;
  • height - defines a custom height for a header line.

Defining header and footer for a specific column

// a simple string
        { id:"col1", header:"Column 1", footer:"Footer 1" }
// an object
            header:[{ text:"Column1", colspan:"2"},{ content:"selectFilter" }],
            footer:[{ text:"Total", rowspan:"2"}, { text:" " } ]

Related sample:  Standard Header (Footer) Implementation

For more details, read the Headers and Footers article.

Widths of Columns

Setting the width of columns

To set widths of columns you should use the width attribute.

Setting the width of a column

    { id:"col1",  width:200 }

Related sample:  Sizing through the 'Width', 'Height' Parameters

Adjusting the width of columns to the parent container

To make a column or several columns fill the unused space of the parent container, use the fillspace attribute with the true value:

   { id:"title", header:"Film title", fillspace:true },
//    ...

The column with the "title" value will take all the free space of the container. If there are more than one column with the enabled fillspace attribute, they will divide the free space between them.

Related sample:  Adjusting Columns to the Parent Container

Distributing free space between columns

If you want columns to divide the width of the datatable proportionally, set fillspace as numbers:

   { id:"title", header:"Film title", fillspace:3 },
   { id:"year", header:"Released in", fillspace:1 },
   // ...

The "title" column is 3 times wider than the "year" column, which is 25 to 75 percent relation.

Related sample:  Adjusting Columns to the Parent Container

Adjusting column width to its content

To adjust the width of a column to the related content size, you can use the adjust attribute. There are three possible options:

  • data - (the default one) adjusts column width to the content of the widest item in it;
  • header - adjusts column width to its header content;
  • true - searches for the widest item among data and header(s) and adjusts column width to its content.
    { id:"title", header:"Film title", adjust:"data" },
    { id:"rank", header:"Rank", adjust:"header" }
    // more columns

Pay attention that the resulting column's width won't be less than minWidth, in case this parameter is set for the column.

In case of a large dataset, you can limit the number of rows that will take part in the calculation of the maximum column width with the help of the adjustBatch attribute of the column config. The property works in tandem with the adjust:"data" or adjust:true attributes.

                {id:"title", adjust:"data", adjustBatch:50},
                {id:"title", adjust:true}
            //data count is big

Related sample:  Adjusting Columns to the Content

For more details, read the Sizing and resizing article.

Built-in Filters

The header or footer of a column can contain a filter. See the full list of available filters.

A filter is set by the content property of the header attribute.

Adding filter to the header of a specific column

    { id:"col1", header:[{ text:"Column 1", colspan:"2"}, { content:"selectFilter" }]},
    {/* ... */}

Related sample:  Filtering. Using Built-in Means

For more details, read the Filtering article.

Built-in Sorting

You are allowed to sort data in columns. The way of sorting depends on the column sorting type. There are several predefined sorting types:

  • "int"
  • "date"
  • "string"
  • "string_strict" (case-sensitive string sorting)
  • "text"
  • "server"
  • "raw"

You can also set a custom sorting type.

The sorting is specified by the sort attribute.

Activating sorting for a specific column

    { id:"col1", sort:"string" },
    {/* ... */}

Related sample:  Sorting. Using Built-in Means

For more details, read the Sorting article.

Text Alignment

To set the text alignment in a column you should use attribute css:

Setting the text alignment in a column

    { id:"col1" css:"myStyle"},//in a separate css class
    { id:"col2", css:{'text-align':'right'} //directly in the attribute

Read more about using the css attribute in the Styling article.

Data Formats

Formatting is applied to date and number values and defined for each column separately. To set some format for a column, use the format attribute.

Setting the format for a specific column

    // data will be formatted according to the current locale
        id:"col2", format:function(value){
            return webix.i18n.numberFormat(value);

Related sample:  Using Date Templates

For more details, read the Number and Date formatting article.

Math in Columns

You can write simple math formulas to specify values in column cells. Formulas can be set for a whole column or for a single cell.

Using formulas for setting values in the whole column

    { id:"col1", math:"[row_id,col_name] + [row_id,col_name]" }

Related sample:  Using Cell References in Formulas

For more details, read the Using Formulas article.

External Data Source for the Column

By default, column cells take values from the main data set of Datatable. You can provide data for the column from any source using the collection or options properties of the column. Column data can be taken from:

  • DataCollection
  • any data component (the source component must be initialized first)
  • URL with the path to the data file
  • array with id-value objects [{ id:1, value:"one"}, ...]
  • array with values ["one", "two"]
  • associative array { 1: "one", 2: "two"}
  • function / proxy
        //ID of datatable
        { id:"product", header:"Product", options:"dash-pro" },
        //path to a script
        { id:"quantity", header:"Quantity", options:"data/goods/" },
        //array of objects
        { id:"price", header:"Unit price", options:[
            { id:"1", value:100 },
            { id:"2", value:200 }
        ] }
    url:"data/orderproducts/", //main data source

Regardless of the way you define options/collection, the column data will be stored in a datacollection and can be accessed via the column configuration, e.g. within a data template:

        { id:"price", header:"Unit price", options:[
            { id:"1", price:100 },
            { id:"2", price:200 }
        template:function(obj, common, val, config){
            //config is column config
            return config.collection.getItem(obj.price).price;
        } }
    url:"data/orderproducts/", //main data source

Related sample:  Datatable: Option collections for columns, filters and editors

DataCollections and Relational Databases

You can display connected tables from relational database in one datatable with the help of the collection property. To unite related tables and display the resulting data in a DataTable, use several DataCollections for each table and set up the DataTable columns to display values from the corresponding collections.

1. Sync the datatable with either of the collections:


2. Specify the other collections as data sources for the corresponding columns:

    view:"datatable", id:"orders_grid",
        { id:"date", header:"Order Date" },
        { id:"employee", header:"Employee", collection:employee },
        // other columns


Through attribute template, you can set a template of cells presentation corresponding to your needs.

Using templates for configuration data of a column

        id:"col4", template:function(obj){
            return obj.col1 + obj.col2*2 + obj.col3*3;

Related sample:  Using String Templates

For more details, read the Data Templates article.


Many aspects of a column can be customized to achieve the desired look-and-feel. Column style can be adjusted in a CSS class and applied through the css attribute.

Applying a CSS class to a specific column

    { id:"col1", css:"someStyle" }

For more details, read the Styling article.

Hiding/Showing Columns

Initially, all the datatable columns are visible by default unless a specific hidden property is used in its configuration:

var grid = new webix.ui({
        //this column is hidden initially
        { id:"col1", header:"Title", hidden:true},
        //this column is visible
        { id:"col2", header:"Rating"}

Through the hideColumn() and showColumn() methods you can manipulate visibility of columns dynamically.

Hiding a column


Setting Hidden/Visible Columns in Groups

Datatable API allows for setting the initially visible group of columns (visibleBatch) as well as show and hide any chosen column group defined by batch property:

grida = new webix.ui({
        { id:"id",  header:"#", css:"rank",  batch:2,   width:50},
        { id:"title", header:"Film title", fillspace:true },
        { id:"year",  batch:1,  header:"Released" , width:80},
        { id:"category", header:"Category", batch:1},
        { id:"votes", batch:3, header:"Votes",  width:100},
        { id:"rating", batch:3, header:"Rating", width:100},
        { id:"rank", header:"Rank", css:"rank",  batch:2,width:50}

Any column group can be shown with the showColumnBatch method that takes column batch value as parameter:

//show show id, rank
//show votes, rating

Related sample:  Column Batches

Adding/Deleting Columns Dynamically

Since datatable columns is an array of JSON objects, you can treat it like any JavaScript array. At any moment you can add elements (columns) to this array and delete elements from it - and then repaint the datatable with the new configuration.

Replacing current columns with new ones

grid.config.columns = [/* collection of columns.. */];

In addition, Webix offers its own API for working with arrays:

  • webix.toArray() - converts an array to "Webix" array;
  • array.insertAt() - inserts an element to array into the specific position;
  • array.removeAt() - removes an element from the array at the specific position.

Adding/Removing Separate Columns

var columns = webix.toArray(grid.config.columns);
    header:"New column"

Related sample:  Adding/removing Columns

Grouping Columns

The functionality is available in Webix Pro edition only.

Column batches can be used to organize groups of columns that are shown/hidden by clicking on the header of an aggregating column:

For these needs a multiple line header is used. The first line of an aggregating column is defined via an object with the following properties:

  • content (string) - content-forming property, here: columnGroup. The property is also used to define header filters;
  • batch (string, number) - ID of the group;
  • groupText (string) - title of the group (it is shown when the group is in a closed state);
  • closed (boolean) - the initial state of the group, false by default;
  • colspan (number) - the number of columns in the group, including the aggregating one.

Also, each column that belongs to some group, should be given a group ID defined by batch property:

    //aggregating column
    { id:"2008_1", header:[
      { content:"columnGroup", closed:true, batch:"2008", groupText:"2008", colspan:12},
    //other columns from the group
    { id:"2008_2",  batch:"2008", header:[null, "February"] },
    { id:"2008_3",  batch:"2008", header:[null, "March"] },
    { id:"2008_4",  batch:"2008", header:[null, "April"] },
    // ...

Related sample:  Grouped Columns in DataTable

Read more about colspans and rowspans in Webix datatable header.

Setting Colspans/Rowspans

The feature is available in Webix Pro edition only.

Datatable allows defining colspans and rowspans by span configuration provided with the dataset within the data property of the grid.

To enable the rowspans and colspans functionality, you should set the spans parameter with the true value in the datatable configuration.

Each rowspan/colspan definition consists of the row id, column id, width and height of the span, value to display and css class to apply:

grida = new webix.ui({
            [1, "title", 3]

Related sample:  Colspans in Datatable

To learn more on this topic, please visit the Datatable Rowspans and Colspans article.

Back to top
If you have not checked yet, be sure to visit site of our main product Webix html5 ui library and page of datagrid javascript product.