Skip to content

Webix Grid widget columns configuration guide

With the help of the columns parameter you can:

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 if editable: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)

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.

Defining header and footer for a specific column
webix.grid({
footer:true,
columns:[
{ id:"col1", header:"Column 1", footer:"Footer 1" }
]
});
// an array
webix.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

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

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

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:

Setting the width of a column
columns:[
{ id:"col1", width:200 }
]

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

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

It is good practice to combine changeable sizing options (fillspace and adjust) with minWidth to ensure correct sizing.

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:

Adding filter to the header of a specific column
columns:[
{
id:"col1",
header:[
{ text:"Column 1", colspan:"2"},
{ content:"selectFilter" }
]
},
{/* ... */}
]

Related sample:  Filtering. Using Built-in Means

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”
Activating sorting for a specific column
columns:[
{ id:"col1", sort:"string" },
{/* ... */}
]

Related sample:  Sorting. Using Built-in Means

You can also set a custom sorting type.

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

Setting the text alignment in a column
<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.

You can format dates and numbers with the format attribute:

Setting the format for a specific column
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

Formatting does not affect the actual data. It's a purely visual feature.

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

You can write simple math formulas 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
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.

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

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;

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.

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.
Using custom templates
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.

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.

Applying a CSS class to a specific column
(columns:[
{ id:"col1", css:"someStyle" }
])

For more details, read the Styling article.

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.

Hiding a column
grid.hideColumn("col2");

Hiding and showing of headers/footers works in a different way. Read more about it here

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.

Replacing current columns with new ones
grid.config.columns = [/* ..new collection of columns.. */];
grid.refreshColumns();
// or insert to the beginning
grid.columns.splice(0, 0, { id:"year", header:"Release" });
grid.refreshColumns();
// or remove the 2nd column
grid.columns.splice(1, 1);
grid.refreshColumns();
// or replace the 3rd column
grid.columns.splice(2, 1, { id:"stars", header:"Rates" });
grid.refreshColumns();

Related sample:  DataGrid: Adding/removing 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.

Resetting columns
// get a copy of all the columns
var columns = grid.getColumns(true);
// add new column
columns.splice(columns.length-1, 0, {
id: "col_"+count,
header:"Column "+count,
hidden:true
});
// repaint the table with modified data
grid.refreshColumns(columns);

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, rank
grida.showColumnBatch(2);
//show votes, rating
grida.showColumnBatch(3);

Related sample:  Column Batches

The functionality is available in Webix DataGrid Pro edition only.

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

The feature is available in Webix DataGrid Pro edition only.

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.