# 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:

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

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;
    }
}

# Methods

# VirtualizedList WithEmptyMessage(Func emptyListMessageGenerator)

Description: Sets a custom empty message component to be displayed when the list does not contain any items.
Parameters:
- emptyListMessageGenerator: A delegate that returns an IComponent to be rendered as the empty message.
Returns: The VirtualizedList instance.

# VirtualizedList WithListItems(IEnumerable listItems)

Description: Populates the list with a collection of items. Internally, the items will be managed in pages for virtualization.
Parameters:
- listItems: An enumerable collection of IComponent items to display.
Returns: The VirtualizedList instance.

# HTMLElement Render()

Description: Renders the VirtualizedList component as an HTMLElement.
Returns: The rendered HTMLElement containing the virtualized list.

# Public Properties

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

# Samples

# Basic Virtualized List

This sample demonstrates how to create a basic VirtualizedList component with a large set of items.

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

public class VirtualizedListBasicSample : IComponent
{
    public HTMLElement Render()
    {
        return 
            // Create a VirtualizedList with items
            VirtualizedList()
                .WithListItems(
                    Enumerable.Range(1, 5000)
                              .Select(number => new VirtualizedListSampleItem($"Item {number}")
                ))
                .Render();
    }
}

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

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

    public HTMLElement Render() => _element;
}

# Virtualized List with Custom Empty Message

This sample shows how to provide a custom empty message when the list has no items.

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

public class VirtualizedListEmptySample : IComponent
{
    public HTMLElement Render()
    {
        return VirtualizedList()
                    .WithEmptyMessage(() => TextBlock("No items found"))
                    .WithListItems(Enumerable.Empty<IComponent>())
                    .Render();
    }
}

# See also

Stack
Grid