Tesserae - Virtualized List

VirtualizedList

Description

VirtualizedList is a collection component designed to efficiently render large sets of items by virtualizing the DOM content. Instead of rendering all items at once, it breaks the dataset into pages and only renders the pages within a defined “materialized window.” As the user scrolls, pages that move out of view are removed while new pages are dynamically added. This approach significantly reduces the number of DOM elements and improves performance, especially when list items involve complex or resource-intensive operations.

Usage

Instantiate the VirtualizedList using the provided static helper method from Tesserae.UI. You can set the list items and optionally provide a custom empty list message. The following example demonstrates how to create a VirtualizedList with a large set of items:

virtualized-list-sample.js

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new VirtualizedListExample();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class VirtualizedListExample : IComponent
    {
        public HTMLElement Render()
        {
            // Create a VirtualizedList with default configuration (4 rows per page, 4 columns per row)
            var virtualizedList = VirtualizedList()
                                      .WithListItems(GetItems());

            // Optionally, set an empty list message
            // var virtualizedList = VirtualizedList()
            //                          .WithEmptyMessage(() => TextBlock("No items available"))
            //                          .WithListItems(Enumerable.Empty<IComponent>());

            return virtualizedList.Render();
        }

        private IEnumerable<IComponent> GetItems()
        {
            return Enumerable.Range(1, 5000)
                             .Select(i => new SampleVirtualizedItem($"Item {i}"));
        }

        public sealed class SampleVirtualizedItem : IComponent
        {
            private readonly HTMLElement _element;

            public SampleVirtualizedItem(string text)
            {
                _element = Div(_(text: text, styles: s =>
                {
                    s.display   = "block";
                    s.textAlign = "center";
                    s.height    = "63px";
                }));
            }

            public HTMLElement Render() => _element;
        }
    }
}

Public Properties

The VirtualizedList does not expose additional public properties. Its configuration is done through the method parameters during instantiation.

API reference

class

VirtualizedList

public class VirtualizedList : IComponent

A VirtualizedList component that renders only the visible portion of a large list to improve performance.

Constructors

Constructor

VirtualizedList

public VirtualizedList(int rowsPerPage = 4, int columnsPerRow = 4)

Initializes a new instance of the VirtualizedList class.

Parameters

rowsPerPage: The number of rows per virtual page.
columnsPerRow: The number of columns per row.

Methods

Method

VirtualizedList.WithEmptyMessage

public VirtualizedList WithEmptyMessage(Func<IComponent> emptyListMessageGenerator)

Sets a message to display when the list is empty.

Parameters

emptyListMessageGenerator: A function that returns the empty list message component.

Returns

The current instance of the type.

Method

VirtualizedList.WithListItems

public VirtualizedList WithListItems(IEnumerable<IComponent> listItems)

Adds items to the virtualized list.

Parameters

listItems: The items to add.

Returns

The current instance of the type.

Method

VirtualizedList.Render

public HTMLElement Render()

Renders the virtualized list.

Returns

The rendered HTMLElement.

Samples

Virtualized List with 5,000 Items

This sample creates 5,000 rows. Only the rows currently in view (plus a small buffer) are actually present in the DOM — scroll rapidly to see the recycler in action. Each row is styled with a fixed height so the scroll position is computed accurately.

virtualized-list-2-sample.js

using System.Linq;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            document.body.style.overflow = "hidden";

            var list = VirtualizedList()
                .WithListItems(Enumerable.Range(1, 5000).Select(n => (IComponent)new Row(n)))
                .Height(400.px());

            MountCenteredToBody(list);
        }
    }

    public sealed class Row : IComponent
    {
        private readonly HTMLElement _el;
        public Row(int n)
        {
            _el = Div(_(styles: s =>
            {
                s.display       = "flex";
                s.alignItems    = "center";
                s.padding       = "0 16px";
                s.height        = "48px";
                s.borderBottom  = "1px solid #eee";
                s.fontFamily    = "monospace";
            }, text: $"Row {n:D5}  ·  hash = {(n * 2654435761U) & 0xFFFFFF:X6}"));
        }
        public HTMLElement Render() => _el;
    }
}

Virtualized List with Custom Empty Message

When the items collection is empty, WithEmptyMessage is used instead. The placeholder can include icons, captions, and call-to-action buttons.

virtualized-list-3-sample.js

using System.Linq;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            document.body.style.overflow = "hidden";

            var list = VirtualizedList()
                .WithEmptyMessage(() =>
                    BackgroundArea(VStack().AlignItemsCenter().JustifyContentCenter().Children(
                        Icon(UIcons.InboxEmpty).XXLarge().Muted(),
                        TextBlock("No data to display").SemiBold().PT(8),
                        TextBlock("Load some records to see them virtualized.").Small().Muted(),
                        Button("Load sample").Primary().SetIcon(UIcons.Refresh).MT(16)
                            .OnClick((s, e) => Toast().Information("Pretend we loaded data..."))
                    ).Padding(24.px())).WS().HS())
                .WithListItems(Enumerable.Empty<IComponent>())
                .Height(280.px());

            MountCenteredToBody(list);
        }
    }
}

VirtualizedList

Description

Usage

Public Properties

API reference

VirtualizedList

Constructors

VirtualizedList

Parameters

Methods

VirtualizedList.WithEmptyMessage

Parameters

Returns

VirtualizedList.WithListItems

Parameters

Returns

VirtualizedList.Render

Returns

Samples

Virtualized List with 5,000 Items

Virtualized List with Custom Empty Message

See also

Referenced by