Configuration

dhtmlxGrid possesses flexible configuration that let you get desired look and feel via a collection of versatile properties.

Columns

It is possible to adjust the configuration of grid columns via the corresponding option columns. As a value it takes an array with objects each of which contains config of a column. The full list of properties you can set for a column is given in the API reference.

var grid = new dhx.Grid("grid_container", {
    columns: [
        { width: 100, id: "a", header: [{ text: "#" }] },
        { width: 100, id: "b", header: [{ text: "Title" }] },
        { width: 200, id: "c", header: [{ text: "Name" }] },
        { width: 200, id: "d", header: [{ text: "Address" }] }
    ],
    data: dataset
});

Each column object may contain a set of properties described below:

  • id - (string|number) the id of a column
  • width - (number) the width of a column
  • header - (array) an array of objects with header rows configuration. Each header object may include:
    • text - (string|number) the text of a header
    • colspan - (number) the number of columns in a colspan
    • rowspan - (number) the number of rows in a rowspan
      Related sample:  Header spans - DHTMLX Grid
    • css - (any) styling to be applied to a header
    • content - (string) additional content of a header, which can be:
      • a filter: "inputFilter" | "selectFilter" | "comboFilter"
      • one of the methods that process values in a column and show result in the header:
        "avg" | "sum" | "max" | "min"
      • some other string
  • footer - (array) an array of objects with footer rows configuration. Each footer object may include:
    • text - (string|number) the text of a header
    • colspan - (number) the number of columns in a colspan
    • css - (any) styling to be applied to a header
    • content - (string) additional content of a header, which can be:
      • a filter: "inputFilter" | "selectFilter" | "comboFilter"
      • one of the methods that process values in a column and show result in the footer:
        "avg" | "sum" | "max" | "min"
      • some other string
  • maxWidth - (number) the maximal width to be set for a column
    Related sample:  Max width - DHTMLX Grid
  • minWidth - (number) the minimal width to be set for a column
    Related sample:  Min width - DHTMLX Grid
  • mark - (object|function) returns a template for marking a cell(s)
    • as an object contains min and max properties, to apply desired CSS classes to cells with minimal|maximal values in a column
    • as a function takes several parameters:
      • cell - (string) the value of a cell
      • columnCells - (array) an array of all cell values in the specified column
      • row - (object) an object with all cells in a row
      • col - (object) the config of a column (see the columns config)
  • resizable - (boolean) defines whether a column can be resized
  • type - (string) the type of a column: "string"|"number"|"boolean"|"any"|"date"
  • editorType - (string) the type of an editor used in a column: "input"|"select"|"datepicker"
  • template - (function) returns a template with content for a cell(s). Takes 3 parameters:
    • cellValue - (any) the value of a cell
    • row - (object) an object with all cells in a row
    • col - (object) the config of a column (see the columns config)
  • hidden - (boolean) defines whether a column is hidden

Hidden columns

You can set the hidden:true property in the config of a column so that it doesn't appear on a page.

{ 
    width: 150, id: "population", header: [{ text: "Population" }] 
},
{ 
    hidden: true, width: 150, id: "yearlyChange", header: [{ text: "Yearly Change" }] }

Related sample:  Hidden columns - DHTMLX Grid

Data

You can specify data for your grid before initialization via the data configuration property. There are also API methods for loading data into grid on the fly. Check the details in the article Data Loading.

var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    data: dataset });

Width/height

You can specify necessary size of your Grid via the configuration properties width and height:

var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    width: 400,       height: 400,      data: dataset
});

In case these options aren't set in the Grid configuration, the component will take the size of the container.

Fitting container size

It is possible to adjust the size of grid to the size of its container with the help of the fitToContainer configuration option, like this:

<div id="grid_container" style="width:600px;height:400px;"></div>
var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    // grid will be adjusted to the size of container
    fitToContainer:true, 
    data: dataset
});

If grid has its own width and height specified, setting the fitToContainer property won't have any effect.

Resizing

Columns of Grid have fixed width with no possibility to change them from UI. You can switch on the corresponding configuration option to make all columns of Grid resizable.

var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    data: dataset,
    resizable: true }

Then you will be able to change the width of columns using the mouse. With the cursor grab the right border and drag to the desired width.

If you also set the fitToContainer configuration option, you will be able to change the width of columns only inside the container of Grid.

You can disable the resizing of any column by setting the resizable:false property in the config of a column.

var grid = new dhx.Grid("grid_container", {
    columns: [
        { width: 150, id: "test1", header: [{ text: "Test1" }] },
        { width: 150, id: "test2", header: [{ text: "Test2" }], resizable: false }     ],
    data: dataset,
    resizable: true }

Related sample:  Resizable columns - DHTMLX Grid

To define the resizing limits, set necessary values to the minWidth/maxWidth properties in the config of a column.

Selection

dhtmlxGrid includes the selection feature that allows highlighting Grid elements depending on the chosen mode. The selection property enables selection in a grid. It can take three values:

  • row - to move selection between Grid rows
  • cell - to move selection between Grid cells
  • complex - to highlight both a selected cell and the row it belongs to
var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    selection:"complex",        data: dataset
});

Related sample:  Selection - DHTMLX Grid

Spans

The component has the spans property that allows you to specify all necessary columns and rows spans right through the initial configuration. It represents an array with spans objects. Each span object contains the following properties:

  • row - (string|number) obligatory, the id of a row
  • column - (string|number) obligatory, the id of a column
  • rowspan - (number) optional, the number of rows in a span
  • colspan - (number) optional, the number of columns in a span
  • text - (string|number) optional, the content of a span
  • css - (string) optional, the name of a CSS class applied to a span
var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    spans: [
        {row:"0", column:"a", rowspan:5 },
        {row:"0", column:"b", rowspan:9, text:"<h2>Some content here</h2>"},
        {row:"0", column:"c", colspan:2, text:"Some content"},
        {row:"10", column:"a", colspan:4, text:"Some header", css:"myCustomColspan"}
    ],
    data: dataset
});

Header/footer content

There are three types of filters that you can specify in the header/footer content of a Grid column:

  • inputFilter - provides a way of filtering data of a Grid column by using a text field
{ 
    width: 160, id: "budget", 
    header: [{ text: "Budget" }, { content: "inputFilter" }] }

Related sample:  Header filter - DHTMLX Grid

  • selectFilter - allows end users to filter data of a column by choosing an option from a presented dropdown list
{ 
    width: 160, id: "status", 
    header: [{ text: "Status" }, { content: "selectFilter" }],     editorType: "select", 
    options: ["Done", "In Progress", "Not Started"] 
}

Related sample:  Header filter - DHTMLX Grid

  • comboFilter - provides a way to filter data of a column by choosing an option from a presented dropdown list. To find an option quickly you can enter text into the edit control.
{
    width: 160, id: "renewals", 
    header: [{ text: "Number of renewals" }, { content: "comboFilter" }],     type: "string", editorType: "combobox", 
    options: ["1 time", "1-2 times", "more than 5 times"] 
}

Related sample:  Header filter - DHTMLX Grid

If you specify comboFilter as the header or footer content of a column, you can set an additional config with properties for it.

var grid = new dhx.Grid("grid_container", {
    columns: [
        {
            width: 150, 
            id: "migrants", 
            header: [
                { text: "Migrants (net)" }, 
                { content: "comboFilter", filterConfig: {readonly: true }}             ] 
        }   
    ],
    data: dataset
}

The list of configuration properties for comboFilter

  • filter - (function) sets a custom function for filtering Combo Box options
  • readonly - (boolean) makes ComboBox readonly (it is only possible to select options from the list, without entering words in the input)
  • template - (function) sets a template of displaying options in the popup list
  • placeholder - (string) sets a placeholder in the input of ComboBox
  • virtual - (boolean) enables dynamic loading of data on scrolling the list of options

Header/footer height

The height of the header/footer of Grid is calculated as a sum of rows which are included into it. To set the height of a row inside the header/footer, use the headerRowHeight/footerRowHeight properties, correspondingly.

var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    // footerRowHeight:50       headerRowHeight: 50    });

The default value of the mentioned properties is 40.

Autowidth for columns

You can configure columns' settings so that their width would automatically adjust to their content. Set the columnsAutoWidth property to true for this purpose.

var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    columnsAutoWidth: true,     data: dataset
});

Header sorting

You can sort content of each Grid column by clicking on its header. However, if you want to disable this feature, you need to set the headerSort to false.

var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    headerSort:false,       data: dataset
});

Frozen columns

You can fix (or "freeze") a column or several columns, so that they will become static, while the rest of columns remain scrollable. There is the splitAt property that splits grid columns into the frozen and movable parts. Just set the number of columns (from the left side of the grid) you want to freeze as a value of the property in the Grid configuration.

var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    splitAt:1,       data: dataset
});

Row height

The default height of a grid row is 40. You can change it and set any other height via the rowHeight property, e.g.:

var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    rowHeight: 30,      data: dataset
});

Row style

There is a possibility to apply some styling to a row via the rowCss property. It is a function that takes the id of a row as a parameter and returns a string with the name of a CSS class.

<style>
    .my_custom_row {
        background: coral;
    }
</style>
 
 
var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    rowCss: function (row) { return row.custom ? "my_custom_row" : "" },     data: dataset
});

Editing Grid and separate columns

dhtmlxGrid provides the editing feature that includes two options:

  • editing of the whole Grid, i.e. of all its columns

To make all columns of the Grid editable, specify the editing option in the configuration of Grid:

var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    data: data,
    editing: true });

Related sample:  Editing data - DHTMLX Grid

  • editing of the specified columns only

This option implies that you can enable/disable editing of particular columns by setting the editing: true property in the configuration of a column:

In the example below all columns will be editable, except for the first one:

var grid = new dhx.Grid("grid", {
    columns: [
        { 
            width:150,id:"project",
            editing:false,             header: [
              {text:"Project"}, {content:"selectFilter"}
            ]
        },
        { width:150, id:"owner", header: [{text:"Owner"},{content:"inputFilter"}]},
        { width:150, id:"hours", header: [{text:"Hours"}, {content:"inputFilter"}]},
        // more columns
    ],
    data: data,
    editing: true
});

And the following example demonstrates an opposite situation when only the first column is editable:

var grid = new dhx.Grid("grid", {
    columns: [
        { 
           width:150,id:"project",
           editing:true,            header: [
            {text:"Project"}, {content:"selectFilter"}
           ]
        },
        { width:150, id:"owner", header: [{text:"Owner"},{content:"inputFilter"}]},
        { width:150, id: "hours", header: [{text:"Hours"}, {content:"inputFilter"}]},
        // more columns
    ],
    data: data
});

Setting type of column editor

You can specify the way of editing the cells of a Grid column depending on its content as simple input, select control, date picker, checkbox or combobox. The type of the used editor is defined by the editorType property of a column. There are five types of column editors:

  • input - an editor for cells with a simple text (the default one, unless a column has type:"date")
// cells of the "project" column will be edited as inputs
var grid = new dhx.Grid("grid", {
    columns: [
        {
            width: 150,
            id: "project",
            header: [{ text: "Project" }, { content: "selectFilter" }]
        }
    // more columns
    ],
    data: data,
    editing: true
});

Related sample:  Editing data - DHTMLX Grid

  • datepicker - an editor for cells with dates (default for a column with type:"date")

To use this editor, you should specify the type:"date" property for a column. It is also possible to set the necessary format of date while editing a cell content with the help of the dateFormat option.

{ 
    // if the type:"date" config is set in the column config, 
    // there's no need to specify the type of the editor
    width: 150, id: "start_date", 
    header: [{ text: "Calendar", colspan: 2 }, { text: "Start date" }], 
    type: "date", dateFormat: "%d/%m/%Y"  }

Related sample:  Editing data - DHTMLX Grid

  • select - an editor for cells that should contain several options to choose from

To set this editor type you need to provide the options property with an array of options to be displayed in the editor, e.g.:

{
    width: 150, id: "status", header: [{text: "Status"}, {content: "selectFilter"}],
    editorType: "select", options: ["Done", "In Progress", "Not Started"] }

Related sample:  Editing data - DHTMLX Grid

  • checkbox - an editor for cells with a two-state check box

To use this editor, you need to specify the type: "boolean" property for a column.

{ 
    // if the type:"boolean" config is set in the column config, 
    // there's no need to specify the type of the editor
    width: 160, id: "test", 
    header: [{ text: "Test" }], 
    type: "boolean" }

Related sample:  Editing data - DHTMLX Grid

If you specify the editing option in the configuration of Grid, then editing of a column with checkbox will always be enabled.

  • combobox - an editor for cells that should contain several options to choose from. There is a possibility to find an option by entering text in the edit control

To use this editor you need to specify the editorType: "combobox" property for a column and provide the options property with an array of options to be displayed in the editor, e.g.:

{
    width: 160, id: "test", header: [{ text: "Test" }], type: "string", 
    editorType: "combobox", options: ["1 time", "1-2 times", "more than 5 times"]  }

Related sample:  Editing data - DHTMLX Grid

Automatic adding of empty row into Grid

There is a possibility to automatically add an empty row into the end of Grid after the last cell of the last empty row in the grid is filled out. Use the autoEmptyRow property in the Grid configuration object to enable this feature:

var grid = new dhx.Grid("grid_container", {
    columns: [// columns config],
    autoEmptyRow:true,       data: dataset
});

Related sample:  Auto Empty Row - DHTMLX Grid

Drag-n-drop of Grid rows

dhtmlxGrid supports drag-n-drop of rows between grids in several modes. To begin with, you should specify the dragMode property in the configuration object of Grid. Then define which mode you need:

  • "target" - a grid takes rows from other grids, while its row can't be dragged out of it
  • "source" - a grid allows dragging its rows out and can't take rows from other grids
  • "both" - a grid both takes rows from other grids and allows dragging its rows out as well
var grid = new dhx.Grid("grid_container", { 
    columns: [
        { id: "country", header: [{ text: "Country" }] },
        { id: "population", header: [{ text: "Population" }] }
    ],
    data: dataset,
    dragMode: "source" });

Related sample:  Setup drag mode - DHTMLX Grid

Back to top