Initializing help system before first use

# vdl-datagrid

Render a table of related array entities. The array entities for each column are defined as child `<vdl-datagrid-column>` elements. The common index sets are automatically detected. The table will emit the following events on user interaction:

- `selection-changed` - Triggered whenever the selected cell is changed, e.g. when user clicks on a cell or starts to edit a cell. This event is triggered on the vdl-datagrid element. The event handler also receives context of the selection, which includes selection cell list, active cell, selection type and whether the selected row changed. This object is describe below as `SelectionChangedDetails`.
- `selection-removed` - Triggered whenever the selection is removed. This event is triggered on the vdl-datagrid element.
- `table-rendered` - Triggered each time the table finishes rendering. This event is triggered on the vdl-datagrid element and the event handler receives the table id, number of rows and number of columns in the table as part of the `evt.detail`.
- `row-moved` - Triggered when the user finishes dragging a row on a datagrid with `movable-rows` enabled. This event is triggered on the vdl-datagrid element and the event handler receives the `RowMovedDetails` object as part of the `evt.detail`.

Add the `compact` class to the parent `vdl-page` to render the Table with compact style.
`

    SelectionChangedDetails: {
       selection: CellDetails[], // An array of cells in the selected row
       activeCell: CellDetails,  // The cell that was clicked when selecting the row
       rowData: any[], // Array of raw data for the selected row
       selectionType: 'ROW',
       selectionChanged: boolean, // Whether the selected row was changed. This is true if the selection is updated to a different row
    }

    CellDetails: {
       value: any,
       rowData: any[],
       element: HTMLElement,
       displayPosition: {row: number, column: number}
    }

    RowMovedDetails: {
       tableId: string,
       rowData: Object,
       originalRowPosition: number,
       destinationRowPosition: number,
       revertRowMove: Function // Callback that can be called to revert the row move
    }

`

since 5.2

### Example

    <vdl-var name="selectedRowData" value="=[]"></vdl-var>
    <vdl-action-group name="handleSelectionChanged">
        <vdl-action-set-var var="selectedRowData" value="=value ? value.activeCell.rowData : []"></vdl-action-set-var>
    </vdl-action-group>

    <vdl-action-group name="handleSelectionRemoved">
        <vdl-action-set-var var="selectedRowData" value="=[]"></vdl-action-set-var>
    </vdl-action-group>

    <vdl-action-group name="handleRenderEvent">
        <vdl-action-message text="='table rendered: rows ' + evt.detail.numberOfRows + ', columns: ' + evt.detail.numberOfColumns"></vdl-action-message>
    </vdl-action-group>

    <vdl-datagrid vdl-event="'selection-changed': actions.handleSelectionChanged, 'selection-removed': actions.handleSelectionRemoved, 'table-rendered': actions.handleRenderEvent">
        <vdl-datagrid-column entity="MY_ARRAY_1"></vdl-datagrid-column>
        <vdl-datagrid-column entity="MY_ARRAY_2"></vdl-datagrid-column>
    </vdl-datagrid>

### Attributes

add-remove-row | This Setting will show the add-remove row buttons at the bottom of the grid. Set to "true" to prompt for index selection on row add. Set to addrow-autoinc will switch the behaviour to allow new index values to be created, incrementing from the highest value in the set(s).This attribute can not be set when "data" attribute is being used. | since 5.2 |  |
always-show-selection | Whether to display selection on inactive grids. Set to true to keep selection on a grid when it becomes inactive. | since 5.2 |  |
cell-render | A custom cell render function or expression that is applied to all cells in the datagrid. This affects the rendered output of the cell only (sorting and filtering are unaffected). The cell-render function should return either the original data unchanged, some new data to display in the cell or a new HTML element to insert into the cell. In addition to returning the original or modified cell value it can also modify the HTML cellElement that is passed in. If a cell-render function is provided on vdl-datagrid and a child vdl-datagrid-column has a render function, then the vdl-datagrid-column render function will take precedence. Note that if you specify a cell render function then labels won't be applied to any cells within the entire table.
Variable | Type | Description
--- | --- | ---
data | (string|boolean|number) | The value of the cell being rendered. Its data type will match that of the array elements in this column. The cell value will be HTML escaped to avoid XSS security issues.
type | string | The type call data requested - this will currently always be display.
rowData | Array.<(string|boolean|number)> | The values from each cell in the current row. The order of the row data reflects the underlying order of the array indices rather than the display order.
columnDefinition | ColumnDefinition | The ColumnDefinition object representing the configuration of the cell's column. See the ColumnDefinition object describe in the column-definition attribute.
cellElement | HTMLElement | The cell HTML element. This can be modified or appended to, affecting the display of the cell.
| since 5.3 | requires expression |
class | Space-separated list of the classes of the element. | since 5.2 |  |
column-definition | Specify how columns are defined. This attribute can only be used in combination with the "data" attribute. Allowed values are: `column-definition="auto"` - Generates columns from the data (default) `column-definition="labels"` - Uses the "label" and "value" properties on an object. Data will be reduced to one row. `column-definition="=[{ field: "name" }, { field: "age" }]"` - An array of objects defining the column properties. When using column properties, you should supply a column definition object for each column you require and each object must have a property named 'field'. The value of the field property must reference a property on the data. Below is an example showing how columns, and even individual cells can be made editable. This also shows how dropdown options can be supplied with labels: data =
    [
       { name: "John Doe", gender: "MALE", age: 30, isStaff: false },
       { name: "Jane Doe", gender: "FEMALE", age: 25, isStaff: true }
    ]
Callback to determine if a cell is editable:
    /* ColumnDefinition
    {
       field: string,
       title: string,
       editable: boolean | ((details: VdlDatagridCellDetails) => boolean),
       parentColumn: false | ColumnDefinition,
       modelEntity: undefined | ModelEntity,
    }
    */

    /* RowDefinition
    {
       rowData: (string|number|boolean|null|undefined)[] | Record

           ,

       treeParentRow: false | RowDefinition,

    }

    */

    /* VdlDatagridCellDetails

    {

       cellValue: (string|number|boolean|null|undefined),

       columnDefinition: ColumnDefinition,

       rowData: (string|number|boolean|null|undefined)[] | Record

            ,

       treeParentRow: false | RowDefinition,

       tableData: (string|number|boolean|null|undefined)[][],

    }

    */

    function isNameEditable(cellDetails: VdlDatagridCellDetails) {

       /* Make use of the cellDetails to determine if a cell is editable... */

       return true;

    }
Callback to construct gender options:
    function constructGenderOptions(cellValue: (string|boolean|number), rowData: {[key: string]: (string|boolean|number)}) {
       return [
           { key: "OTHER", value: "Prefer not to say" },
           { key: "MALE", value: "Male" },
           { key: "FEMALE", value: "Female" }
       ];
    }
column-definition =
    [
       { field: "name", title: "Full Name", editable: isNameEditable },
       { field: "gender", editable: true, editorOptions: constructGenderOptions },
       { field: "age", headerSortStartingDir: "desc", editable: true },
       { field: "isStaff" }
    ]
Object passed to the cell-event handler:
    /* ColumnDefinition
    {
       field: string,
       title: string,
       editable: boolean | ((details: VdlDatagridCellDetails) => boolean),
       parentColumn: false | ColumnDefinition,
       modelEntity: undefined | ModelEntity,
    }
    */

    /* RowDefinition
    {
       rowData: (string|number|boolean|null|undefined)[] | Record

           ,

       treeParentRow: false | RowDefinition,

    }

    */

    /* VdlDatagridCellEditDetails

    {

       cellValue: (string|number|boolean|null|undefined),

       cellInitialValue: (string|number|boolean|null|undefined),

       cellOldValue: (string|number|boolean|null|undefined),

       columnDefinition: ColumnDefinition,

       rowData: (string|number|boolean|null|undefined)[] | Record

            ,

       treeParentRow: false | RowDefinition,

       tableData: (string|number|boolean|null|undefined)[][]

    }

    */
Handling the cell-edit event:
    <script>
    function handler(cellEditDetails: VdlDatagridCellEditDetails) {
       /* cell-edit event handler code */
    }
    </script>

    <vdl-datagrid vdl-event="cell-edit: handler" [...] >
Callback to validate a cell:
    /* VdlDatagridCellDetails
    {
       cellValue: (string|number|boolean|null|undefined),
       columnDefinition: ColumnDefinition,
       rowData: (string|number|boolean|null|undefined)[] | Record

           ,

       treeParentRow: false | RowDefinition,

       tableData: (string|number|boolean|null|undefined)[][],

    }

    */

    function isValidBool(cellDetails: VdlDatagridCellDetails) {

       return true;

    }

    function isValidObject(cellDetails: VdlDatagridCellDetails) {

       return {

          isValid: true,

          errorMessage: "wrong value",

          allowSave:false

       };

    }
Custom sorter:
    <script>
    function customSorter(valueA, valueB, rowA, rowB, columnElement, sortDirection) {
       return valueA > valueB ? 1 : -1;
    }
    const columnDefinitions = [{ field: "name", title: "Full Name", sorter: customSorter }]
    </script>
Custom editor: `cellDetails` - VdlDatagridCellDetails object for the cell (as used in other areas of VDL) `onRendered` - function to call when the editor has been rendered `success` - function to call to pass the successfully updated value to Tabulator `cancel` - function to call to abort the edit and return to a normal cell `editorParams` - params object passed into the editorParams column definition property `columnDefinition` - ColumnDefinition object (as used in other areas of VDL)
    <script>
    const customEditorColumns = [{
        field: 'values',
        editable: true,
        editor: (cellDetails, onRendered, success, cancel, editorParams, column) => {
            var editor = document.createElement("input");
            editor.classList.add('custom-editor');

            onRendered(() => {
                editor.value = cellDetails.cellValue;
                editor.focus();
            });

            function successFunc() {
                success(editor.value + editorParams.suffix);
            }
            editor.addEventListener("blur", successFunc);
            editor.addEventListener("keydown", (e) => {
                if (e.key === 'Escape') cancel()
            })
            return editor;
        },
        editorParams: {
            suffix: '-sfx'
        }
    }]
    </script>

    <vdl-datagrid column-definition="=customEditorColumns" data="=customEditorData"></vdl-datagrid>
Column definition objects accept the following configuration properties:
Variable | Type | Description
--- | --- | ---
field | string | The name of the objects property which holds the columns value.
title | string | The displayed title of the column.
width | number | string | The width of the column, either as a number in pixels, for example 200, or a percentage string such as: '50%'.
headerSortStartingDir | "asc" | "desc" | The header sort starting direction.
cssClass | string | Space seperated class names.
editable | boolean | (details: VdlDatagridCellDetails) => boolean | Optional boolean, or callback which determines if an individual cell can be edited. The callback is invoked when a cell is clicked and is provided with an VdlDatagridCellDetails object to help a decision be made.
dataType | "string" | "number" | "boolean" | Optionally specify the data type for the column. If not provided, type will automatically be inferred from the first row of data.
editorOptions | Array.<(string|boolean|number)> | Object.<string, string> | Array.<{key: (string|boolean|number), value: string}> | Optional editor options array, the presence of which will cause a dropdown of the provided options to appear instead of the usual string, number or checkbox editor.
editorValidate | (details: VdlDatagridCellDetails) => boolean | InsightValidationResult | Optional callback which validate the values in the column's cells. The callback is provided with a VdlDatagridCellDetails.
editor | (cellDetails: VdlDatagridCellDetails, onRendered: function, success: function, cancel: function, editorParams, columnDefinition: ColumnDefinition) => Element | false | Optional callback to provide a custom editor for a cell, returning its DOM node which will be rendered inside the cell, or false to abort editing.
editorParams | any | Additional custom parameters passed to the editor callback.
sorter | (valueA: "string" | "number" | "boolean", valueB: "string" | "number" | "boolean", rowA: RowDefinition, rowB: RowDefinition, columnDefinition: ColumnDefinition, sortDirection: "asc" | "desc") => number | Custom sorter function for the column. The function should return a number less than 0 if valueA is less than valueB, 0 if they are equal, and a number greater than 0 if valueA is greater than valueB.
| since 5.2 | accepts expression |
column-filter | Set this to true to enable the column filters. This will show a header row with filter inputs for each column. | since 5.2 |  |
data | Use this attribute to pass data directly to vdl-datagrid. Supported formats are; array of primitives: `[1,2,3]`, Array of objects: `[{... prop: 1}]`, or an array of arrays: `[...["a",1]]` | since 5.2 | requires expression |
defer-column-filter | Set this to true to defer column filters from applying until the input loses focus. | since 5.3 | accepts expression |
export-filename | The name of the file exported from the table. A file extension will be assigned. | since 5.2 | accepts expression |
freeze-columns | The number of columns to freeze in the table starting from the left hand column. Works best when vdl-datagrid is in a fixed width container | since 5.2 |  |
header-tooltip-render | A custom render function or expression that is called for each header cell in the datagrid and defines how to display the header cell's tooltip.It should return either a string or HTML content to display inside the tooltip, a DOM node to replace the tooltip or an undefined/nullish value to hide the tooltip.
Variable | Type | Description
--- | --- | ---
title | string | The title text from the header cell.
columnDefinition | ColumnDefinition | The ColumnDefinition object representing the configuration of the tooltip cell's column. See the ColumnDefinition object describe in the column-definition attribute.
cellElement | HTMLElement | The tooltip's header cell HTML element.
| since 5.7 | requires expression |
height | Provide a height to contain the datagrid, when page-mode is set to scrolling (default). Accepts integer or css units (50%, 200px). If no unit is specified, it defaults to pixels. | since 5.2 |  |
id | Specify an element id for the grid. Useful if you later want to target the grid using a selector. If not given then an id will be generated. | since 5.2 |  |
movable-rows | If this is enabled then an additional column is added to the left of the table allowing users to drag rows to re-order them. A "row-moved" event is triggered on the vdl-datagrid at the end of a row drag. You can capture this event to update the data and persist the change. The row-moved event is given the row data as an object keyed by the column ids, the original and destination positions and a revertRowMove callback that can be called to revert the change and move the row back to the original position. See the type definition for `RowMovedDetails` at the top of this section. Defaults to false. | since 5.8 |  |
page-mode | By default the grid will show all rows in scrolling mode. Set this attribute to paged to enable grid pagination. | since 5.2 |  |
page-size | The number of rows to show per-page in paged mode. Defaults to 50. | since 5.2 |  |
resizable-columns | Allow users to resize columns by dragging the column edges. The user can also double-click column edges to expand/collapse the column to the size of the contents. It is recommended that you set an "id" attribute on the Datagrid when using this feature so that the column widths can be reinstated to the correct Datagrid on redraw. Resized columns will retain their size on redraw during the current browser session only. Defaults to false. | since 5.8 |  |
row-filter | Expression to be used for filtering the rows of a <vdl-datagrid>. This must be an expression and should resolve to either a function or a boolean value. If a function it will be executed when grid updates. The function will have the following signature (rowData, indices) and should return a boolean.
Variable | Type | Description
--- | --- | ---
rowData | Array.<(string|boolean|number)> | The values from each cell in the current row. The order of the row data reflects the underlying order of the array indices rather than the display order.
indices | Array.<(string|boolean|number)> | Data for the index columns of the row
| since 5.2 | requires expression |
save-state | Set this to false to disable grid state saving. By default grid state is stored in the user's browser session so that user settings (e.g. page, sorting and search) are preserved if grid data is reloaded. | since 5.2 |  |
scenario | The default scenario to use for fetching data in the grid. This can be overridden per column but the default will be used when a column does not specify a particular scenario and the index sets will be fetched from the default scenario. This attribute will not affect the scenario variable in any render expression on the datagrid columns.This attribute can not be set when "data" attribute is being used. | since 5.2 | accepts expression |
show-column-sorting | Show column sorting controls in headers so the user can change column sort order and direction. Defaults to true. | since 5.8 |  |
show-export | Set this to true to display an export to CSV button. | since 5.2 | accepts expression |
tooltip-render | A custom render function or expression that is called for each cell in the datagrid and defines how to display the cell's tooltip.It should return either a string or HTML content to display inside the tooltip, a DOM node to replace the tooltip or an undefined/nullish value to hide the tooltip.The tooltip is not displayed on the bottom-calc row's cells.
Variable | Type | Description
--- | --- | ---
data | (string|boolean|number) | The value of the cell the tooltip is being generated for. Its data type will match that of the array elements in this column. The cell value will be HTML escaped to avoid XSS security issues.
type | string | The type cell data requested - this will currently always be display.
rowData | Array.<(string|boolean|number)> | The values from each cell in the current row. The order of the row data reflects the underlying order of the array indices rather than the display order.
columnDefinition | ColumnDefinition | The ColumnDefinition object representing the configuration of the tooltip cell's column. See the ColumnDefinition object describe in the column-definition attribute.
cellElement | HTMLElement | The tooltip's cell HTML element.
| since 5.3 | requires expression |
width | Provide a width to contain the datagrid. Accepts integer or css units (50%, 200px). If no unit is specified, it defaults to pixels. If no width is provided the width defaults to 100% of its container. | since 5.2 |  |

Parent Topic VDL 5 Reference

© 2001-2026 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.