TreeGridElement Specification

For the authoritative method list and signatures, see the auto-generated api-reference.md. This file focuses on behaviour and usage that signatures alone don't convey.

Overview

TreeGridElement is a Playwright element wrapper for <vaadin-grid> backed by a Vaadin TreeGrid. It extends GridElement with tree-specific APIs for querying hierarchy levels, checking expanded/collapsed/leaf state, and performing single-row or level-based bulk expand and collapse operations.

Note: Vaadin's TreeGrid renders using the same <vaadin-grid> web component as the plain Grid. The hierarchy is expressed through <vaadin-grid-tree-toggle> elements that Vaadin renders inside each row's hierarchy column cell content. TreeGridElement therefore shares the same tag name constant as GridElement and inherits all of its row, cell, header, selection, and sorting APIs.

All row and cell access methods auto-scroll the grid as needed to bring virtualized rows into view.

Tag Name

vaadin-grid

Class Hierarchy

VaadinElement
    └── GridElement
            └── TreeGridElement

Implemented Interfaces

Inherited from GridElement:

Constants

API Methods

Constructor

TreeGridElement(Locator locator)

Creates a new TreeGridElement from a Playwright locator pointing to the <vaadin-grid> element backed by a TreeGrid.

Static Factory Methods

get(Page page)

Get the first TreeGridElement on the page.

TreeGridElement grid = TreeGridElement.get(page);

get(Locator parent)

Get the first TreeGridElement within a parent locator.

TreeGridElement grid = TreeGridElement.get(page.locator("#container"));

getById(Page page, String id)

Get a TreeGridElement by its id attribute.

TreeGridElement grid = TreeGridElement.getById(page, "my-tree-grid");

Row-Level Query Methods

Row-Level Expand / Collapse

Inherited Grid Methods

All GridElement methods are inherited unchanged, including:

• getTotalRowCount(), getRenderedRowCount(), getColumnCount()
• findRow(int rowIndex), findCell(int row, int col), findCell(int row, String header)
• findHeaderCell(...), getHeaderCellContents()
• select(int), deselect(int), getSelectedItemCount()
• checkSelectAll(), uncheckSelectAll(), isSelectAllChecked(), isSelectAllIndeterminate(), isSelectAllUnchecked()
• waitForGridToStopLoading(), scrollToRow(int), scrollToStart(), scrollToEnd()

Inner Classes

TreeRowElement extends GridElement.RowElement

Represents a row in a TreeGrid, extending RowElement with tree-specific state queries and expand/collapse actions. Use findTreeRow(int) to obtain one, or construct from an existing RowElement.

Constructors

// Obtain directly (preferred — use findTreeRow on the grid)
TreeRowElement row = grid.findTreeRow(0).get();

// Upgrade an existing RowElement
TreeRowElement row = new TreeRowElement(grid.findRow(0).get());

Tree-Specific Methods

Inherited RowElement Methods

All RowElement methods are available: getRowLocator(), getRowIndex(), getCell(int), getCell(String), isSelected(), select(), deselect(), openDetails(), closeDetails(), isDetailsOpen().

Implementation Notes

How tree state is read

<vaadin-grid-tree-toggle> exposes three key values, but they are surfaced differently:

Because expanded and leaf are reflected boolean attributes, their presence in the DOM means true and their absence means false. This also means CSS attribute selectors work for them:

// Count all visible expanded toggles using a CSS selector — no JS needed
locator.locator("vaadin-grid-tree-toggle[expanded]").count();

level is not reflected, so it must be read via JavaScript:

toggle.evaluate("el => el.level")  // returns a Number

How the hierarchy column is located

TreeGridElement searches all cells in the row for the one whose cell content contains a <vaadin-grid-tree-toggle>, rather than assuming the toggle is always in cell 0. This correctly handles:

• Multi-select mode: Vaadin inserts a checkbox selection column at DOM index 0, pushing the hierarchy column to index 1.
• Column reordering: The hierarchy column may be at any position.

Why expand/collapse uses a JS synthetic click

<vaadin-grid-cell-content> intercepts pointer events, which causes Playwright's coordinate-based .click() to never reach the <vaadin-grid-tree-toggle> inside it. Toggle clicks are therefore performed via:

toggle.evaluate("el => el.click()")

This matches how Vaadin's own TestBench performs the same operation via Selenium's WebElement.click().

Usage Examples

Basic Tree State Queries

TreeGridElement grid = TreeGridElement.getById(page, "my-tree-grid");

// Row counts
int total = grid.getTotalRowCount();       // visible rows (collapsed children not counted)
int expanded = grid.getExpandedRowCount(); // number of currently expanded rows

// Hierarchy state of row at index 0
boolean isLeaf = grid.isRowLeaf(0);
boolean isExpanded = grid.isRowExpanded(0);
boolean isCollapsed = grid.isRowCollapsed(0);
int level = grid.getRowLevel(0);           // 0 = root

Single-Row Expand / Collapse

TreeGridElement grid = TreeGridElement.getById(page, "my-tree-grid");

// Expand root row 0 (no-op if already expanded or a leaf)
grid.expandRow(0);
assertTrue(grid.isRowExpanded(0));

// Access a child row that is now visible at flat index 1
var child = grid.findCell(1, "Name");
assertEquals("Child 0-0", child.get().getCellContentLocator().innerText());

// Collapse it again
grid.collapseRow(0);
assertEquals(3, grid.getTotalRowCount());

TreeRowElement API

TreeGridElement grid = TreeGridElement.getById(page, "my-tree-grid");

// Obtain a tree-aware row object
TreeGridElement.TreeRowElement row = grid.findTreeRow(0).get();

System.out.println(row.getLevel());    // 0
System.out.println(row.isLeaf());      // false
System.out.println(row.isExpanded());  // false

row.expand();
assertTrue(row.isExpanded());

row.collapse();
assertFalse(row.isExpanded());

Upgrading a RowElement to TreeRowElement

// If you already have a RowElement from a generic helper, wrap it:
GridElement.RowElement plainRow = grid.findRow(0).get();
TreeGridElement.TreeRowElement treeRow = new TreeGridElement.TreeRowElement(plainRow);

assertEquals(0, treeRow.getLevel());
assertFalse(treeRow.isLeaf());

Selection in a Multi-Select TreeGrid

// Multi-select mode adds a checkbox column at index 0.
// TreeGridElement handles this automatically.
TreeGridElement grid = TreeGridElement.getById(page, "multi-select-tree-grid");

grid.select(0);
grid.select(1);
assertEquals(2, grid.getSelectedItemCount());

// Expand, then select a child row too
grid.expandRow(0);
grid.select(1); // first child of row 0
assertTrue(grid.findRow(1).get().isSelected());

// Select-all checkbox
grid.checkSelectAll();
assertTrue(grid.isSelectAllChecked());

grid.uncheckSelectAll();
assertEquals(0, grid.getSelectedItemCount());

Multi-Level Tree (Three Levels)

TreeGridElement grid = TreeGridElement.getById(page, "three-level-tree-grid");
assertEquals(2, grid.getTotalRowCount()); // only root divisions visible

// Expand Division A (index 0) to reveal its departments
grid.expandRow(0);
assertEquals(4, grid.getTotalRowCount()); // 2 divisions + Dept A1, Dept A2

// Expand Dept A1 (now at index 1) to reveal its employees
grid.expandRow(1);
assertEquals(6, grid.getTotalRowCount()); // + Employee A1a, Employee A1b

// Verify grandchild level and leaf state
assertEquals(2, grid.findTreeRow(2).get().getLevel()); // Employee A1a is level 2
assertTrue(grid.findTreeRow(2).get().isLeaf());

// Collapse Division A — hides all its descendants
grid.collapseRow(0);
assertEquals(2, grid.getTotalRowCount());