--- title: GridPro description: GridPro element: vaadin-grid-pro --- ## Description `` is a high quality data grid / data table Web Component with extended functionality. It extends `` and adds extra features on top of the basic ones. See [``](/elements/vaadin-grid) documentation for details. ```html ``` ### Internal components In addition to `` itself, the following internal components are themable: - `` - has the same API as [``](/elements/vaadin-checkbox). - `` - has the same API as [``](/elements/vaadin-text-field). - `` - has the same API as [``](/elements/vaadin-select). ## Properties ### accessibleName **Type:** `string` String used to label the grid to screen reader users. ### activeItem **Type:** `any` The item user has last interacted with. Turns to `null` after user deactivates the item by re-interacting with the currently active item. ### allRowsVisible **Type:** `boolean` If true, the grid's height is defined by its rows. Effectively, this disables the grid's virtual scrolling so that all the rows are rendered in the DOM at once. If the grid has a large number of items, using the feature is discouraged to avoid performance issues. ### cellPartNameGenerator **Type:** `GridCellPartNameGenerator | null | undefined` A function that allows generating CSS `part` names for grid cells in Shadow DOM based on their row and column, for styling from outside using the `::part()` selector. The return value should be the generated part name as a string, or multiple part names separated by whitespace characters. Receives two arguments: - `column` The `` element (`undefined` for details-cell). - `model` The object with the properties related with the rendered item, contains: - `model.index` The index of the item. - `model.item` The item. - `model.expanded` Sublevel toggle state. - `model.level` Level of the tree represented with a horizontal offset of the toggle button. - `model.selected` Selected state. See also: [GridCellPartNameGenerator](#gridcellpartnamegenerator) ### columnRendering **Type:** `ColumnRendering` Allows you to choose between modes for rendering columns in the grid: "eager" (default): All columns are rendered upfront, regardless of their visibility within the viewport. This mode should generally be preferred, as it avoids the limitations imposed by the "lazy" mode. Use this mode unless the grid has a large number of columns and performance outweighs the limitations in priority. "lazy": Optimizes the rendering of cells when there are multiple columns in the grid by virtualizing horizontal scrolling. In this mode, body cells are rendered only when their corresponding columns are inside the visible viewport. Using "lazy" rendering should be used only if you're dealing with a large number of columns and performance is your highest priority. For most use cases, the default "eager" mode is recommended due to the limitations imposed by the "lazy" mode. When using the "lazy" mode, keep the following limitations in mind: - Row Height: When only a number of columns are visible at once, the height of a row can only be that of the highest cell currently visible on that row. Make sure each cell on a single row has the same height as all other cells on that row. If row cells have different heights, users may experience jumpiness when scrolling the grid horizontally as lazily rendered cells with different heights are scrolled into view. - Auto-width Columns: For the columns that are initially outside the visible viewport but still use auto-width, only the header content is taken into account when calculating the column width because the body cells of the columns outside the viewport are not initially rendered. - Screen Reader Compatibility: Screen readers may not be able to associate the focused cells with the correct headers when only a subset of the body cells on a row is rendered. - Keyboard Navigation: Tabbing through focusable elements inside the grid body may not work as expected because some of the columns that would include focusable elements in the body cells may be outside the visible viewport and thus not rendered. See also: [ColumnRendering](#columnrendering) ### columnReorderingAllowed **Type:** `boolean` Set to true to allow column reordering. ### dataProvider **Type:** `GridDataProvider | null | undefined` Function that provides items lazily. Receives arguments `params`, `callback` `params.page` Requested page index `params.pageSize` Current page size `params.filters` Currently applied filters `params.sortOrders` Currently applied sorting orders `params.parentItem` When tree is used, and sublevel items are requested, reference to parent item of the requested sublevel. Otherwise `undefined`. `callback(items, size)` Callback function with arguments: - `items` Current page of items - `size` Total number of items. When tree sublevel items are requested, total number of items in the requested sublevel. Optional when tree is not used, required for tree. See also: [GridDataProvider](#griddataprovider) ### detailsOpenedItems **Type:** `any[]` An array containing references to items with open row details. ### dragFilter **Type:** `GridDragAndDropFilter | null | undefined` A function that filters dragging of specific grid rows. The return value should be false if dragging of the row should be disabled. Receives one argument: - `model` The object with the properties related with the rendered item, contains: - `model.index` The index of the item. - `model.item` The item. - `model.expanded` Sublevel toggle state. - `model.level` Level of the tree represented with a horizontal offset of the toggle button. - `model.selected` Selected state. See also: [GridDragAndDropFilter](#griddraganddropfilter) ### dropFilter **Type:** `GridDragAndDropFilter | null | undefined` A function that filters dropping on specific grid rows. The return value should be false if dropping on the row should be disabled. Receives one argument: - `model` The object with the properties related with the rendered item, contains: - `model.index` The index of the item. - `model.item` The item. - `model.expanded` Sublevel toggle state. - `model.level` Level of the tree represented with a horizontal offset of the toggle button. - `model.selected` Selected state. See also: [GridDragAndDropFilter](#griddraganddropfilter) ### dropMode **Type:** `GridDropMode | null | undefined` Defines the locations within the Grid row where an element can be dropped. Possible values are: - `between`: The drop event can happen between Grid rows. - `on-top`: The drop event can happen on top of Grid rows. - `on-top-or-between`: The drop event can happen either on top of or between Grid rows. - `on-grid`: The drop event will not happen on any specific row, it will show the drop target outline around the whole grid. See also: [GridDropMode](#griddropmode) ### editOnClick **Type:** `boolean | null | undefined` When true, the grid enters cell edit mode on a single click instead of the default double click. ### enterNextRow **Type:** `boolean | null | undefined` When true, pressing Enter while in cell edit mode will move focus to the editable cell in the next row (Shift + Enter - same, but for previous row). ### expandedItems **Type:** `any[]` An array that contains the expanded items. ### isItemSelectable **Type:** `(item: any) => boolean` A function to check whether a specific item in the grid may be selected or deselected by the user. Used by the selection column to conditionally enable to disable checkboxes for individual items. This function does not prevent programmatic selection/deselection of items. Changing the function does not modify the currently selected items. Configuring this function hides the select all checkbox of the grid selection column, which means users can not select or deselect all items anymore, nor do they get feedback on whether all items are selected or not. Receives an item instance and should return a boolean indicating whether users may change the selection state of that item. ### itemHasChildrenPath **Type:** `string` Path to an item sub-property that indicates whether the item has child items. ### itemIdPath **Type:** `string | null | undefined` Path to an item sub-property that identifies the item. ### items **Type:** `any[] | null | undefined` An array containing the items which will be passed to renderer functions. ### loading **Type:** `boolean | null | undefined` `true` while data is being requested from the data provider. ### multiSort **Type:** `boolean` When `true`, all `` are applied for sorting. ### multiSortOnShiftClick **Type:** `boolean` When `true`, Shift-clicking an unsorted column's sorter adds it to the multi-sort. Shift + Space does the same action via keyboard. This property has precedence over the `multiSort` property. If `multiSortOnShiftClick` is true, the multiSort property is effectively ignored. ### multiSortPriority **Type:** `"append" | "prepend"` Controls how columns are added to the sort order when using multi-sort. The sort order is visually indicated by numbers in grid sorters placed in column headers. By default, whenever an unsorted column is sorted, or the sort-direction of a column is changed, that column gets sort priority 1, thus affecting the priority for all the other sorted columns. This is identical to using `multi-sort-priority="prepend"`. Using this property allows to change this behavior so that sorting an unsorted column would add it to the "end" of the sort, and changing column's sort direction would retain it's previous priority. To set this, use `multi-sort-priority="append"`. ### pageSize **Type:** `number` Number of items fetched at a time from the dataprovider. ### rowDetailsRenderer **Type:** `GridRowDetailsRenderer | null | undefined` Custom function for rendering the content of the row details. Receives three arguments: - `root` The row details content DOM element. Append your content to it. - `grid` The `` element. - `model` The object with the properties related with the rendered item, contains: - `model.index` The index of the item. - `model.item` The item. - `model.level` The number of the item's tree sublevel, starts from 0. - `model.expanded` True if the item's tree sublevel is expanded. - `model.selected` True if the item is selected. See also: [GridRowDetailsRenderer](#gridrowdetailsrenderer) ### rowsDraggable **Type:** `boolean | null | undefined` Marks the grid's rows to be available for dragging. ### selectedItems **Type:** `any[]` An array that contains the selected items. ### singleCellEdit **Type:** `boolean | null | undefined` When true, after moving to next or previous editable cell using Tab / Shift+Tab, it will be focused without edit mode. When `enterNextRow` is true, pressing Enter will also preserve edit mode, otherwise, it will have no effect. ### size **Type:** `number` The number of root-level items in the grid. ### slotStyles **Type:** `any` ## Methods ### clearCache **Type:** `() => void` Clears the cached pages and reloads data from dataprovider when needed. ### closeItemDetails **Type:** `(item: any) => void` Close the details row of a given item. ### collapseItem **Type:** `(item: any) => void` Collapses the given item tree. ### deselectItem **Type:** `(item: any) => void` Deselects the given item if it is already selected. ### expandItem **Type:** `(item: any) => void` Expands the given item tree. ### filterDragAndDrop **Type:** `() => void` Runs the `dragFilter` and `dropFilter` hooks for the visible cells. If the filter depends on varying conditions, you may need to call this function manually in order to update the draggability when the conditions change. ### generateCellPartNames **Type:** `() => void` Runs the `cellPartNameGenerator` for the visible cells. If the generator depends on varying conditions, you need to call this function manually in order to update the styles when the conditions change. ### getEventContext **Type:** `(event: Event) => GridEventContext` Returns an object with context information about the event target: - `item`: the data object corresponding to the targeted row (not specified when targeting header or footer) - `column`: the column element corresponding to the targeted cell (not specified when targeting row details) - `section`: whether the event targeted the body, header, footer or details of the grid These additional properties are included when `item` is specified: - `index`: the index of the item - `selected`: the selected state of the item - `detailsOpened`: whether the row details are open for the item - `expanded`: the expanded state of the tree toggle - `level`: the tree hierarchy level - `hasChildren`: whether the item has children The returned object is populated only when a grid cell, header, footer or row details is found in `event.composedPath()`. This means mostly mouse and keyboard events. If such a grid part is not found in the path, an empty object is returned. This may be the case eg. if the event is fired on the `` element and not any deeper in the DOM, or if the event targets the empty part of the grid body. ### getItemId **Type:** `(item: any) => unknown` Returns a value that identifies the item. Uses `itemIdPath` if available. Can be customized by overriding. ### openItemDetails **Type:** `(item: any) => void` Open the details row of a given item. ### requestContentUpdate **Type:** `() => void` Requests an update for the content of cells. While performing the update, the following renderers are invoked: - `Grid.rowDetailsRenderer` - `GridColumn.renderer` - `GridColumn.headerRenderer` - `GridColumn.footerRenderer` It is not guaranteed that the update happens immediately (synchronously) after it is requested. ### scrollToIndex **Type:** `(...indexes: number[]) => void` Scroll to a specific row index in the virtual list. Note that the row index is not always the same for any particular item. For example, sorting or filtering items can affect the row index related to an item. The `indexes` parameter can be either a single number or multiple numbers. The grid will first try to scroll to the item at the first index on the top level. In case the item at the first index is expanded, the grid will then try scroll to the item at the second index within the children of the expanded first item, and so on. Each given index points to a child of the item at the previous index. Using `Infinity` as an index will point to the last item on the level. ### selectItem **Type:** `(item: any) => void` Selects the given item. ## Static Methods ### setDefaultMultiSortPriority **Type:** `any` Sets the default multi-sort priority to use for all grid instances. This method should be called before creating any grid instances. Changing this setting does not affect the default for existing grids. ## Events ### active-item-changed **Type:** `CustomEvent` Fired when the `activeItem` property changes. ### cell-activate **Type:** `CustomEvent` Fired when the cell is activated with click or keyboard. ### cell-edit-started **Type:** [GridProCellEditStartedEvent](#gridprocelleditstartedevent) Fired when the user starts editing a grid cell. ### cell-focus **Type:** `CustomEvent` Fired when a cell is focused with click or keyboard navigation. Use context property of @see {@link GridCellFocusEvent} to get detail information about the event. ### column-reorder **Type:** `CustomEvent` Fired when the columns in the grid are reordered. ### column-resize **Type:** `CustomEvent` Fired when a column in the grid is resized by the user. ### data-provider-changed **Type:** `CustomEvent` Fired when the `dataProvider` property changes. ### enter-next-row-changed **Type:** `CustomEvent` Fired when the `enterNextRow` property changes. ### expanded-items-changed **Type:** `CustomEvent` Fired when the `expandedItems` property changes. ### grid-dragend **Type:** `CustomEvent` Fired when the dragging of the rows ends. ### grid-dragstart **Type:** `CustomEvent` Fired when starting to drag grid rows. ### grid-drop **Type:** `CustomEvent` Fired when a drop occurs on top of the grid. ### item-property-changed **Type:** [GridProItemPropertyChangedEvent](#gridproitempropertychangedevent) Fired before exiting the cell edit mode, if the value has been changed. If the default is prevented, value change would not be applied. ### item-toggle **Type:** `CustomEvent` Fired when the user selects or deselects an item through the selection column. ### loading-changed **Type:** `CustomEvent` Fired when the `loading` property changes. ### selected-items-changed **Type:** `CustomEvent` Fired when the `selectedItems` property changes. ### single-cell-edit-changed **Type:** `CustomEvent` Fired when the `singleCellEdit` property changes. ### size-changed **Type:** `CustomEvent` Fired when the `size` property changes. ## Types ### ColumnRendering ```ts export type ColumnRendering = 'eager' | 'lazy'; ``` ### DataProvider ```ts export type DataProvider> = ( params: DataProviderDefaultParams & TDataProviderParams, callback: DataProviderCallback, ) => void; ``` ### DataProviderCallback ```ts export type DataProviderCallback = (items: TItem[], size?: number) => void; ``` ### GridCellPartNameGenerator ```ts export type GridCellPartNameGenerator = (column: GridColumn, model: GridItemModel) => string; ``` ### GridDataProvider ```ts export type GridDataProvider = DataProvider>; ``` ### GridDataProviderParams ```ts export type GridDataProviderParams = { page: number; pageSize: number; filters: GridFilterDefinition[]; sortOrders: GridSorterDefinition[]; parentItem?: TItem; }; ``` ### GridDragAndDropFilter ```ts export type GridDragAndDropFilter = (model: GridItemModel) => boolean; ``` ### GridDropMode ```ts export type GridDropMode = 'between' | 'on-grid' | 'on-top-or-between' | 'on-top'; ``` ### GridFilterDefinition ```ts export interface GridFilterDefinition { path: string; value: string; } ``` ### GridItemModel ```ts export interface GridItemModel { index: number; item: TItem; selected?: boolean; expanded?: boolean; level?: number; detailsOpened?: boolean; hasChildren?: boolean; } ``` ### GridProCellEditStartedEvent ```ts /** * Fired when the user starts editing a grid cell. */ export type GridProCellEditStartedEvent = CustomEvent<{ index: number; item: TItem; path: string; }>; ``` ### GridProItemPropertyChangedEvent ```ts /** * Fired before exiting the cell edit mode, if the value has been changed. */ export type GridProItemPropertyChangedEvent = CustomEvent<{ index: number; item: TItem; path: string; value: boolean | string; }>; ``` ### GridRowDetailsRenderer ```ts export type GridRowDetailsRenderer = (root: HTMLElement, grid: Grid, model: GridItemModel) => void; ``` ### GridSorterDefinition ```ts export interface GridSorterDefinition { path: string; direction: GridSorterDirection; } ``` ### GridSorterDirection ```ts export type GridSorterDirection = 'asc' | 'desc' | null; ```