GridPro

Description #

<vaadin-grid-pro> is a high quality data grid / data table Web Component with extended functionality. It extends <vaadin-grid> and adds extra features on top of the basic ones.

See <vaadin-grid> documentation for details.

<vaadin-grid-pro></vaadin-grid-pro>

Internal components #

In addition to <vaadin-grid-pro> itself, the following internal components are themable:

• <vaadin-grid-pro-edit-checkbox> - has the same API as <vaadin-checkbox>.
• <vaadin-grid-pro-edit-text-field> - has the same API as <vaadin-text-field>.
• <vaadin-grid-pro-edit-select> - has the same API as <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.

cellClassNameGenerator #

Type: GridCellClassNameGenerator<any> | null | undefined

A function that allows generating CSS class names for grid cells based on their row and column. The return value should be the generated class name as a string, or multiple class names separated by whitespace characters.

Receives two arguments:

• column The <vaadin-grid-column> 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: GridCellClassNameGenerator

cellPartNameGenerator #

Type: GridCellPartNameGenerator<any> | 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 <vaadin-grid-column> 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

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

columnReorderingAllowed #

Type: boolean

Set to true to allow column reordering.

dataProvider #

Type: GridDataProvider<any> | 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

detailsOpenedItems #

Type: any[]

An array containing references to items with open row details.

dragFilter #

Type: GridDragAndDropFilter<any> | 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

dropFilter #

Type: GridDragAndDropFilter<any> | 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

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

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 <vaadin-grid-sorter> 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<any> | 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 <vaadin-grid> 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

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.

generateCellClassNames #

Type: () => void

Runs the cellClassNameGenerator 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.

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<any>

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 <vaadin-grid> 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

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

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 #

export type ColumnRendering = 'eager' | 'lazy';

DataProvider #

export type DataProvider<TItem, TDataProviderParams extends Record<string, unknown>> = (
  params: DataProviderDefaultParams & TDataProviderParams,
  callback: DataProviderCallback<TItem>,
) => void;

DataProviderCallback #

export type DataProviderCallback<TItem> = (items: TItem[], size?: number) => void;

GridCellClassNameGenerator #

/**
 * @deprecated Use `GridCellPartNameGenerator` type and `cellPartNameGenerator` API instead.
 */
export type GridCellClassNameGenerator<TItem> = GridCellPartNameGenerator<TItem>;

GridCellPartNameGenerator #

export type GridCellPartNameGenerator<TItem> = (column: GridColumn<TItem>, model: GridItemModel<TItem>) => string;

GridDataProvider #

export type GridDataProvider<TItem> = DataProvider<TItem, GridDataProviderParams<TItem>>;

GridDataProviderParams #

export type GridDataProviderParams<TItem> = {
  page: number;
  pageSize: number;
  filters: GridFilterDefinition[];
  sortOrders: GridSorterDefinition[];
  parentItem?: TItem;
};

GridDragAndDropFilter #

export type GridDragAndDropFilter<TItem> = (model: GridItemModel<TItem>) => boolean;

GridDropMode #

export type GridDropMode = 'between' | 'on-grid' | 'on-top-or-between' | 'on-top';

GridFilterDefinition #

export interface GridFilterDefinition {
  path: string;
  value: string;
}

GridItemModel #

export interface GridItemModel<TItem> {
  index: number;
  item: TItem;
  selected?: boolean;
  expanded?: boolean;
  level?: number;
  detailsOpened?: boolean;
  hasChildren?: boolean;
}

GridProCellEditStartedEvent #

/**
 * Fired when the user starts editing a grid cell.
 */
export type GridProCellEditStartedEvent<TItem> = CustomEvent<{
  index: number;
  item: TItem;
  path: string;
}>;

GridProItemPropertyChangedEvent #

/**
 * Fired before exiting the cell edit mode, if the value has been changed.
 */
export type GridProItemPropertyChangedEvent<TItem> = CustomEvent<{
  index: number;
  item: TItem;
  path: string;
  value: boolean | string;
}>;

GridRowDetailsRenderer #

export type GridRowDetailsRenderer<TItem> = (root: HTMLElement, grid: Grid<TItem>, model: GridItemModel<TItem>) => void;

GridSorterDefinition #

export interface GridSorterDefinition {
  path: string;
  direction: GridSorterDirection;
}

GridSorterDirection #

export type GridSorterDirection = 'asc' | 'desc' | null;