Webix Grid widget columns configuration guide
With the help of the columns parameter you can:
- specify headers/footers;
- set the width of columns;
- add built-in filters;
- set built-in sorting;
- set the text alignment in a column;
- set the format of data presentation;
- add math formulas;
- specify data source for the column;
- define templates for data presentation;
- define individual CSS class for any column;
- hide/show a column;
- hide/show batches of columns;
- add/delete columns dynamically;
- group columns;
- define colspans and rowspans.
Automatic Column Configuration
Section titled “Automatic Column Configuration”DataGrid can configure its columns based on the data. This is extremely useful for prototyping and creating simple tables. For automatic configuration, enable the autoConfig property. The columns property is not needed in this case.
webix.grid({ autoConfig:true, data:[ { id:"1", title:"Rage against the Machine", stars:5, $css:"top" }, { id:"2", title:"Chalices and Blades", stars:3 }, { id:"3", title:"Look back in Anger", stars:4 }, { id:"4", title:"Look Homeward, Angel", stars:5, $css:"top" } ]})
DataGrid will analyze the data 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 ifeditable:true
in the datagrid configuration);fillspace:true
for the first column,width:100
for the rest;select:"row"
(unless other setting is passed in the datagrid configuration)
Headers/Footers
Section titled “Headers/Footers”The header and footer are enabled by the parameters header and footer, correspondingly (by default, headers are enabled).
The values of header and footer can be defined as a string, object or an array of strings and objects.
1. into a string, you can put into the text, images, HTML inputs, and links. Read more.
2. an object allows you to set more complex headers and footers. The object can have 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 or a counter for values in a column (textFilter, selectFilter or any other from the list of filters). Read more;
- tooltip - the tooltip for cells of the column, read more;
- height - defines a custom height for a header line;
- css - the name of a CSS class that will be applied to the column header.
3. an array allows you to define multiline headers.
webix.grid({ footer:true, columns:[ { id:"col1", header:"Column 1", footer:"Footer 1" } ]});
// an arraywebix.grid({ footer:true, columns:[ { id:"col1", header:[ { text:"Column1", colspan:"2"}, { content:"selectFilter" } ], footer:[ { text:"Total", rowspan:"2"}, { text:" " } ] } ]});
Related sample: Standard Header (Footer) Implementation
Width of Columns
Section titled “Width of Columns”Dynamic Width
Section titled “Dynamic Width”To make a column or several columns fill the unused space of the parent container, set fillspace:true:
columns:[ { id:"title", header:"Film title", fillspace:true }, // ...]
The column will take all the free space of the datagrid container. If there is more than one column with the enabled fillspace attribute, they will equally divide the space.
Related sample: Adjusting Columns to the Parent Container
Proportional Width
Section titled “Proportional Width”If you want columns to divide the width of the datagrid proportionally, set fillspace as a number:
webix.grid({ columns:[ { id:"title", header:"Film title", fillspace:3 }, { id:"year", header:"Released in", fillspace:1 }, // ... ]})
Related sample: Adjusting Columns to the Parent Container
Fixed Width
Section titled “Fixed Width”You can set the fixed width of all the DataGrid columns. Use the columnWidth property in the DataGrid configuration.
webix.grid({ columnWidth:200, columns:[ ] })
To set a fixed width for a specific column, use the width attribute:
columns:[ { id:"col1", width:200 }]
Related sample: Sizing through the 'Width', 'Height' Parameters
Adjusting column width to its content
Section titled “Adjusting column width to its content”To adjust the width of a column to the content size, you can use the adjust attribute. There are three possible options:
- data - the width of the cell with the widest content;
- header - the width of the header text;
- true - a combination of both: it will adjust the column to the widest data or a header cell.
webix.grid({ columns: [ { id: "title", header: "Film", adjust: "data" }, { id: "year", header: "Released in", adjust: "header" }, { id: "notes", header: "Reviews", adjust: true } ]})
If you have huge data, you can limit the number of rows, based on which the width of columns is calculated with adjust. Set the adjustBatch attribute:
webix.grid({ columns:[ {id:"id"}, {id:"title", adjust:"data", adjustBatch:50}, {id:"title", adjust:true} ], //data count is big data:big_film_data});
Related sample: Adjusting Columns to the Content
Good Practice for Dynamic Sizing
Section titled “Good Practice for Dynamic Sizing”It is good practice to combine changeable sizing options (fillspace and adjust) with minWidth to ensure correct sizing.
Built-in Filters
Section titled “Built-in Filters”You can add a filter to a header or a footer. See the full list of available filters.
A filter is set by the content property:
columns:[ { id:"col1", header:[ { text:"Column 1", colspan:"2"}, { content:"selectFilter" } ] }, {/* ... */}]
Related sample: Filtering. Using Built-in Means
Built-in Sorting
Section titled “Built-in Sorting”You can enable sorting for columns. The sorting is specified by the sort attribute. The way of sorting depends on the data type. There are several predefined sorting types:
- “int”
- “date”
- “string”
- “string_strict” (case-sensitive string sorting)
- “text”
- “server”
- “raw”
columns:[ { id:"col1", sort:"string" }, {/* ... */}]
Related sample: Sorting. Using Built-in Means
You can also set a custom sorting type.
Text Alignment
Section titled “Text Alignment”To set the text alignment in a column, use the css attribute:
<style>.myStyle{ text-align:right;}</style>
columns:[ { id:"col1" css:"myStyle"}, //a css class { id:"col2", css:{'text-align':'right'}} //styles directly in the attribute]
Read more about using the css attribute in the Styling article.
Data Formats
Section titled “Data Formats”You can format dates and numbers with the format attribute:
columns:[ // 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
Section titled “Math in Columns”You can write simple math formulas in column cells. Formulas can be set for a whole column or for a single cell.
columns:[ { 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
Section titled “External Data Source for the Column”By default, values in columns are put into cells as they are in data (data key = column ID). Columns also can store sets of options, associated with real values by IDs.

These options are called a column collection and can be used for:
- displaying meaningful values in cells (replacing IDs),
- a list of options for a selection editor in a cell,
- a list of options for a selection filter.
Filtering, sorting, and editing will still be performed on the real data (IDs), but the user should see readable text instead. That’s why we recommend setting selection filters and editors for columns like this and sort them as sort: "text"
.
Adding Column Collections
Section titled “Adding Column Collections”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"]
- object
{ 1: "one", 2: "two"}
- function / proxy
webix.grid({ columns:[ //ID of datagrid { 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:
{ columns:[ { 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: DataGrid: Option collections for columns, filters and editors
You can get to a specific collection via the getColumnConfig() method of DataGrid:
var collection = grid.getColumnConfig("titleId").collection;
Templates
Section titled “Templates”By default, raw field values are displayed in cells. To customise data content and specify which data is displayed,you can use templates. Almost any type of content - images, links, numbers, strings and dates - can be presented using string templates.
webix.grid({ ... columns:[ { id:"title", header:"Film title", template:"<strong>#title#</strong>"}, { id:"year", header:"Release year" , template:"at #year#",} ]});
Related sample: Using String Templates
If you need a more customised solution, you can use a custom template by setting the template attribute as a function. This function takes the following parameters:
- obj - each data item
- common - common elements declared in type
- value - the value of the current cell
- col - the column configuration
- ind - the index of the current data item.
webix.grid({ data:grid_data, columns: [ { id: "title", template: function(obj, common, value, column, index) { return obj.title } } ]});
For more details, read the Data Templates article.
Styling
Section titled “Styling”You can change the look and feel of every column. Column style can be set in a CSS class and applied through the css attribute.
(columns:[ { id:"col1", css:"someStyle" }])
For more details, read the Styling article.
Hiding/Showing Columns
Section titled “Hiding/Showing Columns”Initially, all the datagrid columns are visible by default, unless the hidden property is true for a column:
var grid = webix.grid({ columns:[ //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.
grid.hideColumn("col2");
Hiding and showing of headers/footers works in a different way. Read more about it here
Adding/Deleting Columns Dynamically
Section titled “Adding/Deleting Columns Dynamically”You can add columns and remove columns at runtime directly from its columns array.
Don’t forget to repaint the DataGrid afterwards using the refreshColumns method.
grid.config.columns = [/* ..new collection of columns.. */];grid.refreshColumns();
// or insert to the beginninggrid.columns.splice(0, 0, { id:"year", header:"Release" });grid.refreshColumns();
// or remove the 2nd columngrid.columns.splice(1, 1);grid.refreshColumns();
// or replace the 3rd columngrid.columns.splice(2, 1, { id:"stars", header:"Rates" });grid.refreshColumns();
Related sample: DataGrid: Adding/removing Columns
Working with hidden columns
Section titled “Working with hidden columns”If you work with a DataGrid that contains hidden columns, you should get its columns via the getColumns method passing true as a parameter.
The method returns a copy of all columns including the hidden ones. After the changes are made, you need to reset the DataGrid by passing the new array in the refreshColumns method.
// get a copy of all the columnsvar columns = grid.getColumns(true);
// add new columncolumns.splice(columns.length-1, 0, { id: "col_"+count, header:"Column "+count, hidden:true});
// repaint the table with modified datagrid.refreshColumns(columns);
Setting Hidden/Visible Columns in Batches
Section titled “Setting Hidden/Visible Columns in Batches”You can divide columns in batches and show/hide them. To assign a batch to a column, set the batch property. To set the initially visible batch of columns, use the visibleBatch setting.
var grida = webix.grid({ visibleBatch:1, columns:[ { 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 batch can be shown with the showColumnBatch method that takes column batch value as parameter:
//show id, rankgrida.showColumnBatch(2);//show votes, ratinggrida.showColumnBatch(3);
Related sample: Column Batches
Grouping Columns
Section titled “Grouping Columns”Column batches can be used to organize batches 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 as an object with the following properties:
- content (string) - here it must be columnGroup (the property is also used to define header filters);
- batch (string, number) - the ID of the batch;
- groupText (string) - the title of the batch (it is shown when the batch is closed);
- closed (boolean) - if true, the batch is initially closed; false by default;
- colspan (number) - the number of columns in the batch, including the aggregating one.
webix.grid({ columns:[ //aggregating column { id:"2008_1", header:[ { content:"columnGroup", closed:true, batch:"2008", groupText:"2008", colspan:12}, "January" ]}, //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 DataGrid
Setting Colspans/Rowspans
Section titled “Setting Colspans/Rowspans”DataGrid allows defining colspans and rowspans. Spans are stored in the span property in the dataset.
To enable the rowspans and colspans functionality, set the spans parameter to true in the datagrid configuration.
Each rowspan/colspan definition consists of the row ID, column ID, width/height of the span, the value to display and the css class to apply:
webix.grid({ columns:[...], spans:true, data:{ data:grid_data, spans:[ [1, "title", 3] ] }});
Related sample: Colspans in DataGrid
Read more about colspans and rowspans in the Webix DataGrid header.