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:

Interface	Description
`FocusableElement`	Focus operations
`HasStyleElement`	CSS class support
`HasThemeElement`	Theme attribute support
`HasEnabledElement`	Enabled/disabled state

Constants¶

Constant	Value	Description
`FIELD_TAG_NAME`	`"vaadin-grid"`	Same tag as `GridElement`

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¶

Method	Return Type	Description
`findTreeRow(int rowIndex)`	`Optional<TreeRowElement>`	Like `findRow` but returns a `TreeRowElement` with tree-specific APIs; auto-scrolls if needed
`isRowExpanded(int rowIndex)`	`boolean`	`true` if the row's tree toggle has `expanded = true`
`isRowCollapsed(int rowIndex)`	`boolean`	`true` if the row has children but is not expanded
`isRowLeaf(int rowIndex)`	`boolean`	`true` if the row has no children (`leaf = true` on the toggle)
`getRowLevel(int rowIndex)`	`int`	0-based hierarchy depth of the row (root items = 0)
`getExpandedRowCount()`	`int`	Number of currently visible expanded rows

Row-Level Expand / Collapse¶

Method	Description
`expandRow(int rowIndex)`	Expand the row. No-op if already expanded or a leaf node
`collapseRow(int rowIndex)`	Collapse the row. No-op if already collapsed or a leaf node
`toggleRow(int rowIndex)`	Toggle expanded/collapsed state. No-op if the row is a leaf

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¶

Method	Return Type	Description
`getTreeToggleLocator()`	`Locator`	Locator for the `<vaadin-grid-tree-toggle>` in this row's hierarchy cell
`isExpanded()`	`boolean`	`true` if this row is expanded
`isCollapsed()`	`boolean`	`true` if this row has children but is not expanded
`isLeaf()`	`boolean`	`true` if this row has no children
`getLevel()`	`int`	0-based hierarchy depth of this row
`expand()`	`void`	Expand this row. No-op if already expanded or a leaf
`collapse()`	`void`	Collapse this row. No-op if already collapsed or a leaf
`toggle()`	`void`	Toggle expanded/collapsed state. No-op if a leaf

Inherited RowElement Methods¶

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

Implementation Notes¶

How tree state is read¶

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

Value	Reflected as HTML attribute?	How it is read
`expanded`	Yes	`toggle.getAttribute("expanded") != null`
`leaf`	Yes	`toggle.getAttribute("leaf") != null`
`level`	No (DOM property only)	`toggle.evaluate("el => el.level")`

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());