Skip to main content

Configuration

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

Width/height​

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

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

Related sample: Grid. Custom sizes

info

If the width and height options aren't set in the Grid configuration, the Grid will take the size of its container. If you don't specify the height for the container, it will be equal to "0px" and Grid won't be visible on the page.

Autoheight for Grid​

If you use PRO version of DHTMLX Grid, you may enable the auto height mode of Grid. For this, set the value of the height property to "auto". In this mode, Grid will expand on adding new rows, and will shrink on removing rows not to occupy external place.

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

This functionality is available from v8.1.

Related sample: Grid. Set automatic height (PRO)

If needed, you may set the minimal and maximal height for the container via the min-height and max-height CSS properties:

<div class="grid" id="grid_container"></div>

<style>
    .grid {
        min-height: 400px;
        max-height: 600px;
    }
</style>

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.

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

note

You will find the full list of the configuration properties of a Grid column here.

Alignment​

Starting from v6.5, there is the ability to align data in a column as well as to align data in the column's header via the align option:

const grid = new dhx.Grid("grid_container", {
    columns: [
        { id: "name", header:  [{ text: "Name", align: "center" }], align: "right"}
        // more options
    ],
    data: dataset
});

Related sample: Grid. Content align

The available values of the option are "left", "center" and "right".

Autosize for columns​

You can configure columns' settings so that their width would automatically adjust to their content. Use the adjust property for this purpose. The property can take one of four values:

"header"adjusts the columns to the width of their header
"footer"adjusts the columns to the width of their footer
"data"adjusts the columns to the width of their content
truecombines the above mentioned modes and adjusts the column to the bigger value

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

Related sample: Grid. Adjust columns by header, data, all

It is also possible to use the adjust property in the configuration of a separate column:

const grid = new dhx.Grid("grid_container", { 
    columns: [
        { id: "country", header: [{ text: "Country" }], adjust: "header" },
        { id: "population", header: [{ text: "Population" }] }
    ],
    adjust: false,
    data: dataset
});
note

In case complex HTML content is added into a column, the column width may be calculated incorrectly.

Autowidth for columns​

It is possible to automatically adjust the size of Grid columns to the size of Grid with the help of the autoWidth configuration option, like this:

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

Related sample: Grid. Columns auto width

You can disable this functionality for a specified column via setting the autoWidth property to false in the configuration of the column:

const grid = new dhx.Grid("grid_container", {
    columns: [
        { width: 200, id: "country", header: [{ text: "Country" }], autoWidth: false },
        { width: 150, id: "population", header: [{ text: "Population" }] },
    ],
    autoWidth: true,
    data: dataset
});

Formatting columns​

Starting from v7.1, you can display the values of the cells of a Grid column in the desired format:

1. To define the format for numeric values, apply the format configuration option of the column:

{ 
    width: 150, id: "population", header: [{ text: "Population" }],  
    format: "# #.0"
}
// -> 1415045928 will be displayed as 1 415 045 928.0

The following characters can be used:

  • # - the integer part of the number
  • 0 - the fractional part of the number. The 0 placeholder displays insignificant zeros if a number has fewer digits than there are zeros in the format string, for instance, the .00 format will display 0.298 as 0.30.
    If a number has more digits to the right of the decimal point than there are placeholders in the format string, the number rounds to as many decimal places as there are placeholders, for instance, the .000 format will display 0.2 as 0.200.
  • # # - sets the thousands separator in a number (123 456)
  • #.0 - sets the separator for the decimal point in a number (123 456.357)

2. You can display the percentage value in the necessary format by setting the type: "percent" configuration option of a column together with the format option:

{ 
    width: 150, id: "yearlyChange", header: [{ text: "Yearly Change" }], 
    type: "percent", format: "#.00"
}
// -> 0.0039 will be displayed as 0.39%

When using just the type: "percent" configuration option of a column, the result will be the following:

{ 
    width: 150, id: "yearlyChange", header: [{ text: "Yearly Change" }], 
    type: "percent"
}
// -> 0.0039 will be displayed as 0%

3. To define the format for dates, set the type: "date" property for a column and define the format of dates with the help of the format option:

{ 
    width: 150, id: "date", header: [{ text: "Date" }], 
    type: "date", format: "%M %d %Y"
}
info

The date format must include delimiters (space or symbol), otherwise an error will be thrown

Related sample: Grid. Data formats

Frozen columns​

You can fix (or "freeze") a column or several columns, so that they will become static when you scroll the grid, while the rest of columns remain movable.

  • To fix columns to the left side of the grid, use the leftSplit property.
  • To fix columns to the right side of the grid, use the rightSplit property.

Just set the number of columns you want to freeze as a value of the related property in the Grid configuration.

const grid = new dhx.Grid("grid_container", {
    columns: [
        // columns config
    ],
    leftSplit: 1,
    rightSplit: 2,
    data: dataset
});

Related sample: Grid. Frozen columns and rows

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: Grid. Hidden columns

Sortable columns​

By default, DHTMLX Grid allows sorting content of any Grid column by clicking on its header.

To disable this option, set the sortable property in the Grid configuration to false:

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

Related sample: Grid. Sortable columns

Making separate columns sortable​

You can make separate columns sortable by specifying the sortable:true property in the configuration of a column:

In the example below all columns will be sortable, except for the second one:

const grid = new dhx.Grid("grid_container", {
    columns: [
        { width: 200, id: "country", header: [{ text: "Country" }], sortable: true },
        { width: 150, id: "land", header: [{ text: "Land" }] },
        { width: 150, id: "density", header: [{ text: "Density" }], sortable: true }
    ],
    data: dataset,
    sortable: false,  
});

The following sample demonstrates the same result:

const grid = new dhx.Grid("grid_container", {
    columns: [
        { width: 200, id: "country", header: [{ text: "Country" }] },
        { width: 150, id: "land", header: [{ text: "Land" }], sortable: false },
        { width: 150, id: "density", header: [{ text: "Density" }] }
    ],
    data: dataset
});

Resizable columns​

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.

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

note

If you also set the autoWidth 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.

const 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: Grid. Resizable columns

note

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

HTML content of Grid columns​

DHTMLX Grid allows adding HTML content into Grid cells (such as images, icons, text styles, etc.). You can enable the possibility to add HTML content both for the whole Grid and for a particular column, or even for a certain column header/footer. Below you'll find all the available options:

  • setting HTML content for all Grid columns

This way presupposes making each cell of Grid capable of displaying the HTML content via using the htmlEnable property in the configuration object of Grid.

const dataset = [
    {
        "country": "China",
        "flag": "<img src='../flags/cn.jpg' />",
        "id": "1"
    }
];

const grid = new dhx.Grid("grid_container", {
    columns: [
        // columns config
    ],
    data: dataset,
    htmlEnable: true
});
  • setting HTML content for a particular column

If you want to add custom elements into cells of the specified column, you need to set the htmlEnable:true property in the configuration of a column:

const dataset = [
    {
        "country": "<span>China</span><img src='../flags/cn.jpg' />",
        "id": "1"
    }
];

const grid = new dhx.Grid("grid_container", {
    columns: [
        {
            width: 200, id: "country", header: [{ text: "Country" }],
            htmlEnable: true
        }, 
        { 
            width: 150, id: "urban", header: [{ text: "Urban Pop" }] 
        }, 
        // more columns
    ],
    data: dataset
});

Related sample: Grid. Html in data

  • setting HTML content for the header/footer of a column

You can set HTML content in the header or the footer of a column independently. The htmlEnable property enabled for the header/footer redefines the value of the same config specified for the parent column and for the whole Grid:

const grid = new dhx.Grid("grid", {
    columns: [
        { width: 200, id: "country", header: [
            {
                text: "<span style='font-size:16px; color: steelblue'>Country</span>",
                htmlEnable: true,
            }
        ]},
        // other columns' configs
    ],
    data: dataset,
    htmlEnable: false
});

Related sample: Grid. Styling header cells (custom CSS)

Event handlers for HTML content​

HTML elements defined in the data set​

Starting from v7.0, you can add event handlers to the HTML elements defined in a data set of Grid with the help of the eventHandlers configuration property, for instance:

const data = [
    {
        "country": "<div className='cell__html'><span>China</span><img src='../flags/cn.svg'></div>",
        "population": "1415045928", "yearlyChange": "0.0039",
        "netChange": "5528531", "density": "151",
        "urban": "0.5800", "id": "1"
    },
    // more options
];

const grid = new dhx.Grid("grid_container", {
    columns: [
        { width: 200, id: "country", header: [{ text: "Country" }], htmlEnable: true },
        // more options
    ],
    data: data,
    eventHandlers: {
        onclick: {
            cell__html: function(event, data) {
                console.log(JSON.stringify(data.col, null, 2));
            },
        },
        onmouseover: {
            cell__html: function(event) {
                console.log("You are over " + event.target.tagName);
            },
        }
    }
});

Related sample: Grid. Handling events in template

HTML elements in the header/footer cell​

The Suite version 8.3 brought the possibility to add events handlers for the header/footer cell's content. Use the eventHandlers configuration property for this purpose:

const grid = new dhx.Grid("grid", {
    columns: [
        {
            width: 60,
            id: "paid",
            header: [
                {
                   text: `
                       <label className="dhx_checkbox dhx_cell-editor__checkbox ">
                          <input type="checkbox" className="dhx_checkbox__input dhx_checkbox--check-all"/>
                          <span className="dhx_checkbox__visual-input "></span>
                       </label>
                   `,
                   rowspan: 2,
                   htmlEnable: true,
                }
            ],
            type: "boolean",
            sortable: false,
        },
         // more columns
    ],
    data,
    eventHandlers: { 
        onclick: { 
            "dhx_checkbox--check-all": function(event, data) {
                grid.data.forEach(row => {
                    grid.data.update(row.id, {
                        [data.col.id]: event.target.checked,
                    });
                });
            }
        },
    },
});

Related sample: Grid. Rich example with templates and different editors

Editing Grid and separate columns​

DHTMLX Grid 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 editable option in the configuration of Grid:

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

Related sample: Grid. Editing with different editors (combobox, select, multiselect, boolean, date)

  • editing of the specified columns only

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

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

const grid = new dhx.Grid("grid_container", {
    columns: [
        { 
            width: 150, id:"project",
            editable: 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,
    editable: true
});

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

const grid = new dhx.Grid("grid_container", {
    columns: [
        { 
           width: 150, id: "project",
           editable: 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
});

Types of column editor​

You can specify the way of editing the cells of a Grid column depending on its content as simple input, date picker, textarea control, checkbox, select, multiselect or combobox. The type of the used editor can be defined either by the editorType property of a column or via the type one.

There are several types of column editors:

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
const grid = new dhx.Grid("grid_container", {
    columns: [
        {
            width: 150,
            id: "project",
            header: [{ text: "Project" }, { content: "selectFilter" }]
        }
    // more columns
    ],
    data: data,
    editable: true
});

Related sample: Grid. Editing with different editors (combobox, select, multiselect, boolean, date)

  • 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 format 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", format: "%d/%m/%Y" 
}

Related sample: Grid. Editing with different editors (combobox, select, multiselect, boolean, date)

info

You can configure the date picker by passing properties of Calendar (except for the value, range, and dateFormat ones) to the editorConfig object, as in:

{ 
    id: "start_date", 
    header: [{ text: "Start date" }], 
    type: "date", 
    format: "%d/%m/%Y %H:%i",
    editorConfig: { 
        timePicker: true, 
        weekStart: "sunday",  
        thisMonthOnly: true, 
        weekNumbers: true
    } 
}

An editor for cells that contain text.

To use this editor, you should specify the editorType:"textarea" property for a column.

note

The textarea editor allows editing multiple lines of text when the autoHeight:true configuration option of Grid is enabled. The functionality is available only in PRO version of the DHTMLX Grid (or DHTMLX Suite) package.

const grid = new dhx.Grid("grid_container", {
    columns: [
        {
            width: 150, id: "project", 
            header: [{ text: "Project" }, { content: "selectFilter" }], 
            editorType: "textarea"
        }
    // more columns
    ],
    data: data,
    editable: true,
    autoHeight: true
});

Related sample: Grid. Editing with different editors (combobox, select, multiselect, boolean, date)

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: Grid. Editing with different editors (combobox, select, multiselect, boolean, date)

note

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

An editor for cells that should contain several options to choose from.

To set this editor type you need to specify the editorType:"select" property for a column and define a list of options via the options property.

You may either specify the same list of editor options for all cells of the column. For that, use either an array of string values or an array of options' objects as a value of the property as in:

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

// or
{
    width: 150, id: "status", header: [{text: "Status"}, {content: "selectFilter"}],
    editorType: "select", 
    options: [
        { id: "done", value: "Done" }, 
        { id: "in progress", value: "In Progress" }, 
        { id: "not started", value: "Not Started" },
    ],
}

Related sample: Grid. Editing with different editors (combobox, select, multiselect, boolean, date)

Or define unique lists of options for different column cells. For that, use a function as a value of the property:

{
    id: "select_example",
    header: [{ text: "Select example" }],
    editorType: "select",
    options: (column, row) => getCurrentOptions(row),
},

Related sample: Grid. Individual option lists for select, multiselect and combobox editors

  • multiselect​

An editor for cells that enables selection of multiple options. You can select one option, several options, all options, or no options.

To set this editor type you need to specify the editorType:"multiselect" property for a column and define a list of options via the options property.

You may either specify the same list of editor options for all cells of the column. For that, use either an array of string values or an array of options' objects as a value of the property as in:

{
    id: "renewals", type: "string",
    header: [{ text: "Number of renewals" }],
    editorType: "multiselect",
    options: ["1 time", "1-2 times", "more than 5 times"],
}, 

// or
{
    id: "renewals", type: "string",
    header: [{ text: "Number of renewals" }],
    editorType: "multiselect",
    options: [
        { id: "1", value: "1 time" }, 
        { id: "1-2", value: "1-2 times" }, 
        { id: "5+", value: "more than 5 times" },
    ],
}

Related sample: Grid. Editing with different editors (combobox, select, multiselect, boolean, date)

Or define unique lists of options for different column cells. For that, use a function as a value of the property:

{
    id: "multiselect_example",
    header: [{ text: "Multiselect example" }],
    type: "string",
    editorType: "multiselect",
    options: (column, row) => getCurrentOptions(row), 
    minWidth: 360
},

Related sample: Grid. Individual option lists for select, multiselect and combobox editors

If you use the multiselect editor, you can predefine several options to be shown in a cell. You should separate the options in the dataset using the , separator.

const data = [
    {
        renewals: "1 time", //one option is shown in a cell
        ...
    },
    {
        renewals: "more than 5 times, 1 time" //two options are shown in a cell
        ...
    }
];

Configuring the multiselect editor​

There is a list of configuration settings you may provide for the multiselect editor type. Use the editorConfig property to specify the desired settings:

{
       id: "renewals", type: "string",
    header: [{ text: "Number of renewals" }],
    editorType: "multiselect",
    options: ["1 time", "1-2 times", "more than 5 times"],
    editorConfig: {selectAllButton:true}
}

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 define a list of options via the options property.

You may either specify the same list of editor options for all cells of the column. For that, use either an array of string values or an array of options' objects as a value of the property as in:

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

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

Related sample: Grid. Editing with different editors (combobox, select, multiselect, boolean, date)

Or define unique lists of options for different column cells. For that, use a function as a value of the property:

{
    id: "combobox_example",
    header: [{ text: "Combobox example" }],
    editorType: "combobox",
    options: (column, row) => getCurrentOptions(row),
    minWidth: 160
},

Related sample: Grid. Individual option lists for select, multiselect and combobox editors

Configuring the combobox editor​

There is a list of configuration settings you may provide for the combobox editor type. Use the editorConfig property to specify the desired settings:

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

Editing columns with the "number" type​

For columns with the type:"number" setting the editorConfig object may contain the following properties. They are:

  • min - (optional) the minimum allowed value
  • max - (optional) the maximum allowed value
const grid = new dhx.Grid("grid", {
  columns: [
    {
      id: "col1",
      width: 180,
      type: "number",
      editorConfig: { min: 5, max: 100 },
    },
    // more columns
  ]
});

In case a user enters a value that goes beyond the limits specified by the above settings, the entered value is highlighted in red:

Validation of columns with the number type

If the user ignores the warning and still tries to enter an unallowable value, it will be replaced with the minimum/maximum value defined in the editorConfig object by the min/max values. Thus, in the above example the entered value 200 will be replaced with 100, since it is the upper limit set in the editor configuration.

Related sample: Grid. Editing with different editors

Styling the warning​

There is a possibility to redefine the style of the warning on entering an invalid number value. You need to change the dhx_cell-editor__input--not-valid class for this purpose. Here is what it looks like:

.dhx_cell-editor__input--not-valid {
    color: var(--dhx-color-primary);
    font-weight: var(--dhx-font-weight-medium);
}

Editable combobox​

From v7.3, you may allow end users to add new options into the combobox editor (editorType: "combobox") from UI. To activate the functionality, specify the newOptions: true attribute of the editorConfig property in the configuration of the column:

{
    width: 150,
    id: "status",
    header: [{text: "Status"}, {content: "selectFilter"}],
    editorType: "combobox",
    // enables the ability to add new values into the combobox editor of the "Status" column
    editorConfig: { newOptions: true },
    options: ["Done", "In Progress", "Not Started"]
},

Related sample: Grid. Rich example with templates and different editors

The new option will be added into the combobox after the user types a new value into the input field and either presses "Enter" or clicks on the appeared Create "newValue" option in the drop-down list.

At the same time, the created option will also appear in the drop-down list of the header/footer filters (content: "selectFilter" | "comboFilter") of the column:

To localize the Create option, translate the corresponding string and apply a ready locale to the Combobox component:

const locale = {
      en: {
        createItem: "Create"
      },
      de: {
        createItem: "Schaffen"
      }
};

dhx.i18n.setLocale("combobox", locale["de"]);

Opening editor with one click​

By default, you can open the editor by double-clicking on a cell. But if you need the editor to open after a single click, apply the cellClick event of the grid.

note

Note, that it does not work for the select editor (editorType: "select") and you need to use the combobox editor (editorType:"combobox") if you want a drop-down list to open on the mouse click.

Header/footer filters​

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: Grid. Header filters (comboFilter, inputFilter, selectFilter)

  • 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: Grid. Header filters (comboFilter, inputFilter, selectFilter)

  • 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: Grid. Header filters (comboFilter, inputFilter, selectFilter)

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

const 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
  • multiselection - (boolean) enables selection of multiple options
  • readonly - (boolean) makes ComboBox readonly (it is only possible to select options from the list, without entering words in the input). The default value of the readonly property depends on the following conditions:
    • the readonly:true is set as a default value, if htmlEnable:true is set for a column and there is no template specified for a column
    • in all other cases, readonly:false is set by default
  • placeholder - (string) sets a placeholder in the input of ComboBox
  • virtual - (boolean) enables dynamic loading of data on scrolling the list of options
  • template - (function) a function which returns a template with content for the filter options. Takes an option item as a parameter

Customizing header/footer filters​

To add a custom function with your you own logic for the filter of a Grid column, you need to set the customFilter attribute when configuring the header/footer content of the column.

note

The customFilter attribute can be used when content: "inputFilter" | "selectFilter" | "comboFilter" is set.

const grid = new dhx.Grid("grid_container", {
    columns: [
        { width: 150, id: "country", header: [
            { text: "Country" },
            { 
                content: "comboFilter",
                // filters values by the same length
                customFilter: (value, match) => value.length === match.length
            }
        ]},   
    ],
    data: dataset
});

Related sample: Grid. Custom filters in the header

The customFilter attribute is a function which compares the value of each cell of the column with the value which is selected in the header/footer filter of the column. If the value of the cell matches the specified criteria, the function returns true, otherwise, it returns false.

Header/footer height​

You can change the height of the header/footer in one of the following ways:

  1. Specify the necessary height of the rows in the header/footer via the related API options

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. The default value of the mentioned properties is 40.

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

Related sample: Grid. Header, footer and rows height

  1. Provide the automatic adjustment of the header/footer height for the content to fit in

Use the headerAutoHeight and footerAutoHeight configuration options of Grid (PRO version only) to redefine the autoHeight config for the header and the footer, correspondingly:

// enabling autoheight only in the content
const grid1 = new dhx.Grid("grid", {
    columns: [
        // columns config
    ],
    data: dataset,
    autoHeight: true, // enable autoHeight in the data (content)
    headerAutoHeight: false, // disable autoHeight in the header
    footerAutoHeight: false, // disable autoHeight in the footer
});

// enabling autoheight only in the header
const grid2 = new dhx.Grid("grid", {
    columns: [
        // columns config
    ],
    data: dataset,
    autoHeight: false, // disable autoHeight in the data, the header and the footer
    headerAutoHeight: true, // enable autoHeight in the header
});

Related sample: Grid. Header/footer autoHeight mode

Rows​

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

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

Related sample: Grid. Header, footer and rows height

In this case, the height of each row is 30.

Setting height for a separate row​

Starting with v7.1, it is possible to specify the height for the necessary row of data in Grid via setting the number value to the height option when defining the data set:

const dataset = [
    {
        "country": "China",
        "population": "1415045928",
        "height": 80,
        "id": "1"
    },
    {
        "country": "India",
        "population": "1354051854",
        "id": "2",
    }
];

Related sample: Grid. Row height

note

The height option has a higher priority than the autoHeight:true configuration property of Grid.

Autoheight for rows​

Pro version only

This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.

Starting from v7.1, you can set the autoHeight: true option in the configuration of Grid to make long text split into multiple lines automatically based on the width of the column:

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

Related sample: Grid. Rows auto height

As a result, the height of the cells will automatically adjust to their content.

note

Please note that the autoHeight option does not adjust the height of the cells of the header/footer of Grid.

The option just makes their text split into multiple lines, but the height of the cells will remain the same. To set the height of the rows in the header/footer, you can:

Automatic adding of empty row into Grid​

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

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

Related sample: Grid. Auto empty row

Frozen rows​

You can fix (or "freeze") a row or several rows, so that they will become static when you scroll the grid, while the rest of rows remain movable.

  • To fix rows on the top of the grid, use the topSplit property.
  • To fix rows on the bottom of the grid, use the bottomSplit property.
const grid = new dhx.Grid("grid_container", {
    columns: [
        // columns config
    ],
    topSplit: 3,
    bottomSplit: 2,
    data: dataset
});

Related sample: Grid. Frozen columns and rows

Drag-n-drop​

The drag-n-drop functionality allows you to reorder one or several rows or columns inside the grid or between several grids.

Pro version only

If you use GPL version of DHTMLX Grid (or DHTMLX Suite), you will be able to reorder only rows and only one by one.

Note, to be able to drag-n-drop a column and (or) multiple rows, you need to use PRO version of the DHTMLX Grid (or DHTMLX Suite) package.

Drag-n-drop inside the grid​

It is possible to reorder a row or column of Grid by drag and drop. To enable the functionality, define the dragItem: "both" property in the configuration object of Grid:

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

Related sample: Grid. Drag-n-drop

note

To activate the functionality for columns or rows separately, use dragItem: "column" or dragItem: "row" respectively.

If needed, you can disable the drag-n-drop functionality for a separate column via the draggable configuration option of the column:

const grid = new dhx.Grid("grid_container", {
    columns: [
        { width: 200, id: "country", header: [{ text: "Country" }]},
        { width: 150, id: "land", header: [{ text: "Land" }] },
        { width: 150, id: "density", header: [{ text: "Density" }], draggable: false }
    ],
    data: dataset,
    dragItem: "column", 
});
tip

To make the process of work with drag and drop more flexible, you can apply the related drag-n-drop events of Grid for columns and rows.

Drag-n-drop between grids​

DHTMLX Grid supports drag-n-drop of rows/columns 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 a row/column from other grids, while its row/colmn can't be dragged out of it
  • "source" - a grid allows dragging its row/column out and can't take a row/column from other grids
  • "both" - a grid both takes a row/column from other grids and allows dragging its row/column out as well
const grid = new dhx.Grid("grid_container", { 
    columns: [
        { id: "country", header: [{ text: "Country" }] },
        { id: "population", header: [{ text: "Population" }] }
    ],
    data: dataset,
    dragMode: "source",
    // dragItem: "column" - allows reordering columns one by one
});

Related sample: Grid. Drag-n-drop between grids

Drag-n-drop of multiple rows​

Pro version only

This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.

To allow a user to drag-n-drop multiple rows at once, you need to enable multiselection of rows when configuring drag-n-drop. For example:

const grid = new dhx.Grid("grid", {
    columns: [
        // columns config
    ],
    data: data,
    selection: "row",
    //drag-n-drop rows inside the grid
    multiselection: true,
    dragItem: "both" // or dragItem: "row"
});

Related sample: Grid. Drag-n-drop

or

const grid = new dhx.Grid("grid", {
    columns: [
        // columns config
    ],
    data: dataset,
    selection: "row",
    //drag-n-drop rows between grids
    multiselection: true,
    dragMode: "both" // or dragMode: "source"
});

Keyboard Navigation​

DHTMLX Grid provides the keyboard navigation that will help you manipulate your grid faster.

Default shortcut keys​

There are four navigation keys that Grid enables by default:

PageUpscroll Grid up to the height of the visible content (without change of the selected cell)
PageDownscroll Grid down to the height of the visible content (without change of the selected cell)
Homenavigate to the beginning of the Grid content (without change of the selected cell)
Endnavigate to the end of the Grid content (without change of the selected cell)

If you need to disable this functionality, set the keyNavigation property to false.

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

Related sample: Grid. Key navigation

Arrow shortcut keys​

In case you want to enable the arrow keys that allow moving the selection between cells, you need to specify the selection property for Grid.

const grid = new dhx.Grid("grid_container", {
    columns: [
        // columns config
    ],
    data: dataset,
    selection: "complex",
    keyNavigation: true // true - by default
});

Related sample: Grid. Key navigation

The list of the arrow shortcut keys:

ArrowUpmove selection to the previous vertical cell
ArrowDownmove selection to the next vertical cell
ArrowLeftmove selection to the previous horizontal cell
ArrowRightmove selection to the next horizontal cell
Ctrl+ArrowUpmove selection to the first vertical cell
Ctrl+ArrowDownmove selection to the last vertical cell
Ctrl+ArrowLeft move selection to the first horizontal cell
Ctrl+ArrowRight move selection to the last horizontal cell
Tab move selection to the next horizontal cell or the first cell of the next row
Shit+Tab move selection to the previous horizontal cell or to the first cell of the previous row

The arrow shortcut keys listed below do not work when the selection property is set to "complex". Use another mode ("cell" or "row") in case you you want to activate these navigation keys:

Shift+ArrowUpmove selection to the previous vertical cell with the change of the selected cells
Shift+ArrowDownmove selection to the next vertical cell with the change of the selected cells
Shift+ArrowLeftmove selection to the previous horizontal cell with the change of the selected cells
Shift+ArrowRightmove selection to the next horizontal cell with the change of the selected cells
Ctrl+Shift+ArrowUpmove selection to the first vertical cell with the change of the selected cells
Ctrl+Shift+ArrowDownmove selection to the last vertical cell with the change of the selected cells
Ctrl+Shift+ArrowLeftmove selection to the first horizontal cell with the change of the selected cells
Ctrl+Shift+ArrowRightmove selection to the last horizontal cell with the change of the selected cells

Shortcut keys for editing​

It is also possible to use shortcut keys for editing a cell in Grid by setting editable:true property in the configuration object of Grid.

const grid = new dhx.Grid("grid_container", {
    columns: [
        // columns config
    ],
    data: dataset,
    selection: "complex",
    editable: true,
    keyNavigation: true // true - by default
});

Related sample: Grid. Key navigation

The list of the shortcut keys for editing:

Enteropen the editor in the selected cell. If the editor is currently opened - close the editor and save changes
Escapeclose the editor of the selected cell without saving

Selection​

DHTMLX Grid 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:

rowto move selection between Grid rows
cellto move selection between Grid cells
complexto highlight both a selected cell and the row it belongs to

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

Related sample: Grid. Selection

Multiple selection of Grid cells​

While setting the selection property to "row", "cell", or "complex" value, you can enable the multiselection property to allow a user to select multiple Grid elements:

const grid = new dhx.Grid("grid_container", {
    columns: [
        // columns config
    ],
    multiselection: true,
    selection: "row",
    data: dataset
});

Related sample: Grid. Multiselection

Since the multiselection configuration option is set to true, using the "Ctrl + Click" combination allows selecting the desired cells or rows. A range of Grid cells/rows can be selected by clicking the first element to select and then, while holding down the Shift key, clicking the last element to select.

Spans​

The Grid 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
tooltip(boolean) enables a tooltip on hovering over the content of a span, true by default

const 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
});

Related sample: Grid. Grouped cells (spans)

Note, that if both the spans and leftSplit properties are set in the Grid config, the following rules will be applied:

  • All necessary columns or rows will be in a span if the spans property is set for the columns located within the frozen area.
  • If the spans property is set for a number of columns or rows placed as in the frozen part as in the movable one, then the columns remained in the movable part only will be in a span.

Tooltip​

Grid tooltips​

The default configuration of Grid provides tooltips that are rendered when a user hovers over the content of a column's cell. All the tooltips can be controlled via the tooltip configuration property of Grid. By default, the tooltips are enabled. You can disable them, by setting the config to false:

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

Related sample: Grid. Hiding tooltips

The tooltip configuration option can be set as an object with the following properties:

  • force - (optional) forces opening of a tooltip; if set to true, the showDelay and hideDelay settings are ignored, false by default
  • showDelay - (optional) the time period that should pass before showing a tooltip, in ms
  • hideDelay - (optional) the time period that should pass before hiding a tooltip, in ms
  • margin - (optional) the margin between the node and tooltip; 8px by default
  • position - (optional) the position of a tooltip: "right", "bottom", "center", "left", "top"; "bottom" by default
  • css - (optional) the style of a tooltip box
const grid = new dhx.Grid("grid_container", {
    columns: [
        // columns config
    ],
    data: dataset,
    tooltip: {
       force: true
    }
});

Related sample: Grid. Tooltip config

It is also possible to control the header and footer tooltips, independently. There are the headerTooltip and footerTooltip Grid configuration properties, that you can use for this purpose:

const grid = new dhx.Grid("grid_container", {
    columns: [
        // columns config
    ],
    data: dataset,
    tooltip: false, // Disable all tooltips
    headerTooltip: true, // Enable all header tooltips
    footerTooltip: true, // Enable all footer tooltips
});

The headerTooltip and footerTooltip configs can be specified as objects the same as the main tooltip config.

Column and span tooltips​

There is a possibility to enable/disable tooltips for separate columns or spans by using the tooltip option in the configuration object of the columns or spans accordingly:

const grid = new dhx.Grid("grid_container", {
    columns: [
        { width: 200, id: "country", header: [{ text: "Country" }], tooltip: true }, 
        { width: 150, id: "population", header: [{ text: "Population" }] },
    ],
    spans: [
        { row: "1", column: "country", rowspan: 5, tooltip: true }, 
    ],
    data: dataset,
    tooltip: false 
});

The same as with the common Grid tooltips, column and span tooltips can be set as objects with the following properties:

  • force - (optional) forces opening of a tooltip; if set to true, the showDelay and hideDelay settings are ignored, false by default
  • showDelay - (optional) the time period that should pass before showing a tooltip, in ms
  • hideDelay - (optional) the time period that should pass before hiding a tooltip, in ms
  • margin - (optional) the margin between the node and tooltip; 8px by default
  • position - (optional) the position of a tooltip: "right", "bottom", "center", "left", "top"; "bottom" by default
  • css - (optional) the style of a tooltip box
const grid = new dhx.Grid("grid_container", {
    columns: [
        { width: 200, id: "country", header: [{ text: "Country" }], tooltip: { force: true } }, 
        { width: 150, id: "population", header: [{ text: "Population" }] },
    ],
    spans: [
        { row: "1", column: "country", rowspan: 5, tooltip: { force: true } }, 
    ],
    data: dataset,
    tooltip: false 
});

Column header/footer tooltip​

The tooltip set for a column enables/disables all its tooltips. However, you can control the tooltips of the column header/footer separately, by specifying the tooltip property in the corresponding header/footer object inside the column:

const grid = new dhx.Grid("grid", {
    columns: [
        // Enables a tooltip for the country title
        { id: "country", header: [{ text: "Country", tooltip: true }] }, 
        { id: "population", header: [{ text: "Population" }] },
           // more columns
    ],
    data: dataset,
    tooltip: false,
});

What is more, you can specify a necessary template for the header/footer tooltip via the tooltipTemplate configuration property, as in:

const grid = new dhx.Grid("grid", {
    columns: [
        {
            id: "country",
            header: [
                {
                    text: "Country",
                    tooltipTemplate: (value, header, column) => {
                        return `This is column template: ${value}`
                    }
                },
            ],
            footer: [
                {
                    text: "Total",
                    tooltipTemplate: (value, footer, column) => false, // Disabled footer tooltip
                }
            ],
        },
        // more columns
    ],
    data: dataset,
});

Related sample: Grid. Header/footer tooltip

Tooltips for complex data​

You can specify a tooltip as a value for a complex header/footer content, such as the methods processing column values: "avg" | "sum" | "max" | "min" | "count". What is more, you can provide a tooltip template for the header/footer content of any type, which allows showing tooltips for filters.

Check the example below:

const balanceTemplate = value => {
    return value > 0
        ? `<div style='color:green'>⬆ $${value}</div>`
        : `<div style='color:red'>⬇ $${value}</div>`;
};

const grid = new dhx.Grid("grid", {
    columns: [
        {
            minWidth: 150,
            id: "project",
            header: [
                {text: "Project"},
                {content: "comboFilter", tooltipTemplate: () => "Select project"}
            ],
            footer: [{text: "Total"}],
            resizable: true,
            draggable: false
        },
        {
            width: 130,
            id: "balance",
            header: [{text: "Balance"}, {content: "inputFilter"}],
            footer: [
                {
                    content: "sum",
                    tooltipTemplate: balanceTemplate
                },
            ],
            template: balanceTemplate,
            htmlEnable: true,
            format: "#.0",
        },
    ],
});