Skip to main content

header

Required. An array of objects with header rows configuration

Usage​

header: [
    {
        text?:
            string |
            ((content: {
                [key: string]: string | number | null
            }) => string),
        tooltip?: boolean | object, // true by default
        tooltipTemplate?: (
            content: {
                [key: string]: string | number | null;
                value: string;
            },
            header: IHeader,
            column: ICol
        ) => string | boolean,
        align?: "left" | "center" | "right", // "left" by default
        colspan?: number,
        rowspan?: number,
        css?: string,
        content?: "inputFilter" | "selectFilter" | "comboFilter" | "dateFilter",
        filterConfig?: {
            placeholder?: string, // sets an input placeholder for `inputFilter`, `comboFilter` and `dateFilter`
            icon?: string, // sets CSS class for the filter icon in `inputFilter` and the calendar icon in `dateFilter`
            /* properties of `comboFilter` configuration */
            filter?: (item, input: string) => boolean,
            multiselection?: boolean, // false by default
            readonly?: boolean, // false by default
            virtual?: boolean, // true by default
            template?: function,
            /* properties of `dateFilter` configuration */
            asDateObject?: boolean, // false by default
            date?: Date | string,
            mark?: (date: Date) => string,
            disabledDates?: (date: Date) => boolean,
            weekStart?: "saturday" | "sunday" | "monday", // "sunday" by default
            weekNumbers?: boolean, // false by default
            mode?: "calendar" | "year" | "month" | "timepicker", // "calendar" by default
            timePicker?: boolean, // false by default
            dateFormat?: string, //  by default, applies the dateFormat used for the column
            timeFormat?: 24 | 12, // 24 by default
            thisMonthOnly?: boolean, // false by default
            width?: string | number, // "250px" by default
            range?: boolean // false by default
        },
        customFilter?: (
            value: string | number | Date | Date[],
            match: string | string[] | Date | Date[]
        ) => boolean,
        headerSort?: boolean, // true by default
        sortAs?: (cellValue) => string | number,
        htmlEnable?: boolean, // false by default
    }
];

Parameters​

Each header object may include:

text(optional) the text of a header or a callback function which is called with the following parameter:
  • content - an object with the content of the header tooltip that contains the calculated values as key:value pairs, where
    • the key is either the key defined in the list or the functor name
    • the value can be a string/number or null
    The calculated values are taken either from the summary config option of the component or the summary config option of a column
tooltip(optional) enables/disables the header tooltip, or sets the configuration object with the tooltip settings; true by default. When set as an object, the tooltip config can have 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
tooltipTemplate(optional) sets a template for the header tooltip. Takes into account the htmlEnable property. The value of the tooltipTemplate property is a callback function which is called with the following parameters:
  • content - an object with the content of the header tooltip. Contains two properties which are available either from the component's or from the column's configuration:
    • value - the value rendered in a cell, including the applied templates
    • an object with the calculated values of the summary property, set as key:value pairs where:
      • the key is either the key defined in the list or the functor name
      • the value can be a string/number or null
  • header - the object of the column header
  • column - the object of a column
Return false to disable the tooltip
align(optional) aligns data in the header: "left" | "center" | "right", "left" by default
colspan(optional) the number of columns in a colspan
rowspan(optional) the number of rows in a rowspan
css(optional) styling to be applied to a header
content(optional) defines the content of the column header, including the filter type. Allows setting one of the predefined filters:
  • "inputFilter" — a text input field
  • "selectFilter" — a dropdown list
  • "comboFilter" — a combobox with search
  • "dateFilter" (PRO version) — a filter with a calendar for selecting a date or a date range
filterConfig(optional) a configuration object for setting the behavior and appearance of the filter. The set of properties depends on the filter type specified in the content property:

- a configuration object for "inputFilter" can contain the following properties:
  • placeholder - (optional) the placeholder text in the input field
  • icon - (optional) the CSS class for the filter icon

- a configuration object for "comboFilter" can contain a set of properties:
  • filter - (optional) sets a custom function for filtering Combo Box options
  • multiselection - (optional) enables selection of multiple options, false by default
  • readonly - (optional) 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 - (optional) sets a placeholder in the input of ComboBox
  • virtual - (optional) enables dynamic loading of data on scrolling the list of options, true by default
  • template - (optional) a function which returns a template with content for the filter options. Takes an option item as a parameter:
    • item - (object) an option item
- a configuration object for "dateFilter" (PRO version) can contain a set of properties:
Main properties:
  • icon - (optional) the CSS class for the calendar icon
  • placeholder - (optional) the placeholder text in the input field when no date is selected
  • asDateObject - (optional) determines how the filter processes data for customFilter and the beforeFilter and filterChange events. If true, the comparison is performed using Date objects, false by default
  • range - (optional) enables the date range selection mode (from and to), false by default
  • dateFormat - (optional) the date display format (e.g., "%d/%m/%Y"). By default, applies the dateFormat used for the column
Calendar API configuration properties:
  • date - (optional) - the initial date opened in the calendar
  • mark - (optional) - a function for adding custom CSS classes to specific dates
  • disabledDates - (optional) - a function for disabling the selection of specific dates
  • weekStart - (optional) - the start day of the week ("saturday", "sunday" (default), "monday").
  • weekNumbers - (optional) - shows week numbers if true, false by default
  • mode - (optional) - the calendar display mode ("calendar" (default), "year", "month", "timepicker")
  • timePicker - (optional) - adds the ability to select time, false by default
  • timeFormat - (optional) - the time format (12 or 24 (default) hours)
  • thisMonthOnly - (optional) - if true, allows selecting dates only within the current month, false by default
  • width - (optional) - the width of the dropdown calendar, "250px" by default
customFilter (optional) a callback function that allows defining custom filtering logic. It takes two parameters:
  • value - (required) the cell value in the row
  • match - (required) the value selected in the filter
and returns true, if the row matches the filtering criteria, otherwise false
headerSort(optional) enables/disables sorting by clicking the header, true by default
sortAs(optional) a function that defines the type to sort data as (e.g. string, number, date, etc.)
htmlEnable(optional) false by default. If set to true, allows using and displaying HTML content in a header. If set to false, the content of the header cells will be displayed as a string value

Example​

const grid = new dhx.Grid("grid_container", {
    columns: [
        { id: "title", header: [{ text: "Title" }] },
        // more columns configuration objects
    ],
    // more options
});

Related article: Configuration

Related sample: Grid. Grouped headers (spans)