Skip to content

VirtualListElement 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

VirtualListElement is a Playwright element wrapper for the <vaadin-virtual-list> web component. It wraps a virtualized scrollable list that lazily renders items as the user scrolls. It provides helpers for scrolling, querying visible rows, accessing rendered item content, and retrieving typed component elements inside items.

Tag Name

vaadin-virtual-list

Class Hierarchy

VaadinElement
    └── VirtualListElement

Implemented Interfaces

Interface Description
FocusableElement Focus operations
HasStyleElement Style attribute support

Constants

Constant Value Description
FIELD_TAG_NAME "vaadin-virtual-list" HTML tag name

API Methods

Constructor

VirtualListElement(Locator locator)

Creates a new VirtualListElement from a Playwright locator.

Static Factory Methods

get(Page page)

Get the first VirtualListElement on the page.

VirtualListElement list = VirtualListElement.get(page);

Properties / Getters

Method Description
getRowCount() Total number of items (including items not yet rendered)
getFirstVisibleRowIndex() 0-based index of the first visible row
getLastVisibleRowIndex() 0-based index of the last visible row
getVisibleRowCount() Count of rows visible in the viewport
isRowInView(int rowIndex) Whether the given row index is currently visible

All visibility methods flush the connector debouncer before reading the property.

Item Query Methods

Method Description
getRenderedItems() Locator for all currently rendered child elements
getItemByIndex(int index) Locator for the rendered item at the given virtual index (must be in view)
getItemByText(String text) Locator for the first rendered item containing the given text

Component Query Methods

Method Description
getItemComponent(int index, Class<T> type) Get a typed component from the item at the given virtual index
getItemComponentByText(String text, Class<T> type) Get a typed component from the item matching the given text
getComponent(Class<T> type) Get the first typed component found in any rendered item

Component query methods read the tag from the @PlaywrightElement annotation on the target class and require a public constructor accepting a single Locator parameter.

Scroll Actions

Method Description
scrollToRow(int rowIndex) Scroll the list so the given row index becomes visible
scrollToStart() Scroll to the very beginning of the list
scrollToEnd() Scroll to the very end of the list

Assertions

Method Description
assertRowCount(int expected) Assert the total number of items matches (auto-retry)
assertEmpty() Assert the list has zero items
assertRowInView(int rowIndex) Assert the given row is currently visible (auto-retry)
assertRowNotInView(int rowIndex) Assert the given row is NOT currently visible (auto-retry)
assertFirstVisibleRow(int expected) Assert the first visible row index (hasJSProperty, auto-retry)
assertLastVisibleRow(int expected) Assert the last visible row index (hasJSProperty, auto-retry)
assertItemRendered(String text) Assert an item containing the given text is visible in the DOM

Usage Examples

Basic Scrolling

VirtualListElement list = new VirtualListElement(page.locator("#my-list"));

list.scrollToRow(50);       // scroll to index 50
list.scrollToStart();       // scroll to the top
list.scrollToEnd();         // scroll to the bottom

Querying Items

VirtualListElement list = new VirtualListElement(page.locator("#my-list"));

// Total item count (including non-rendered)
int total = list.getRowCount();

// Visibility info
int first = list.getFirstVisibleRowIndex();
int last = list.getLastVisibleRowIndex();
int visible = list.getVisibleRowCount();
boolean inView = list.isRowInView(50);

// Get rendered items
Locator allRendered = list.getRenderedItems();
Locator itemAtIndex = list.getItemByIndex(0);
Locator itemByText = list.getItemByText("Item 1");

Getting Typed Components Inside Items

VirtualListElement list = new VirtualListElement(page.locator("#my-list"));

// Get a ButtonElement from item at index 0
ButtonElement btn = list.getItemComponent(0, ButtonElement.class);

// Get a ButtonElement from item matching text
ButtonElement btn = list.getItemComponentByText("Row 1", ButtonElement.class);

// Get the first ButtonElement in any rendered item
ButtonElement btn = list.getComponent(ButtonElement.class);

Scroll and Read

VirtualListElement list = new VirtualListElement(page.locator("#my-list"));

list.scrollToRow(50);
list.assertItemRendered("Item 51");
assertThat(list.getItemByText("Item 51")).isVisible();

Assertions

VirtualListElement list = new VirtualListElement(page.locator("#my-list"));

// Row count
list.assertRowCount(100);
list.assertEmpty();

// Visibility
list.assertRowInView(0);
list.assertRowNotInView(99);
list.assertFirstVisibleRow(0);
list.assertLastVisibleRow(10);

// Item content
list.assertItemRendered("Item 1");

Empty List

VirtualListElement empty = new VirtualListElement(page.locator("#empty-list"));
empty.assertEmpty();
assertEquals(0, empty.getRowCount());
  • ListBoxElement - Non-virtualized list with selection support