# Items List

# ItemsList

# Description

ItemsList is a flexible list component designed for displaying small sets of items. It belongs to the Collections group and can render items in different layouts depending on the specified columns. When provided with multiple columns, it renders the items using a grid layout; if fewer than two columns are provided, it falls back to a horizontal stack layout. This component is ideal for scenarios where you want to display items without the overhead of virtualization, and it supports customizing the message shown when the list is empty.

# Usage

The ItemsList component can be instantiated using the static helper methods provided by the Tesserae.UI class. It accepts either an array of IComponent items or an ObservableList along with one or more column width definitions (of type UnitSize). If the columns are more than one, a grid layout is used; otherwise, a stack layout is used.

Below is a basic example of how to create an ItemsList:

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

public class ItemsListExample
{
    public static void Main()
    {
        // Create a list of sample items
        var items = new IComponent[]
        {
            Card(TextBlock("Item 1")).MinWidth(200.px()),
            Card(TextBlock("Item 2")).MinWidth(200.px()),
            Card(TextBlock("Item 3")).MinWidth(200.px())
        };

        // Create an ItemsList with a single column (stack layout)
        var list = ItemsList(items, 100.percent())
                        .WithEmptyMessage(() => BackgroundArea(Card(TextBlock("Empty list").Padding(16.px())))
                        .WidthStretch().HeightStretch().MinHeight(100.px()));

        // Render the list
        var element = list.Render();
        // Append the rendered element to the document body
        document.body.appendChild(element);
    }
}

# Methods

WithEmptyMessage(Func emptyListMessageGenerator)
- Description: Specifies a custom message component that is displayed when the list has no items.
- Parameters:
  - emptyListMessageGenerator: A function that returns an IComponent. This component is used as the empty list message.
- Returns: The same ItemsList instance to allow for fluent chaining.

# Properties

ObservableList Items
- Description: Holds the collection of items that will be rendered by the ItemsList component. You can modify this list dynamically to update what is rendered.
HTMLElement StylingContainer
- Description: Exposes the underlying container element for styling purposes.
bool PropagateToStackItemParent
- Description: Indicates whether additional styling or behavior should be propagated to parent elements in the stack layout. This is useful when integrating with other Tesserae components.

# Samples

# Basic ItemsList with Single Column

This sample demonstrates a basic ItemsList rendered as a stack when only one column (or width) is specified.

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

public class BasicItemsListExample
{
    public static void Main()
    {
        // Create a simple array of card components as items
        var items = new IComponent[]
        {
            Card(TextBlock("Item 1")).MinWidth(200.px()),
            Card(TextBlock("Item 2")).MinWidth(200.px()),
            Card(TextBlock("Item 3")).MinWidth(200.px())
        };

        // ItemsList is instantiated with a single column (stack layout)
        var itemsList = ItemsList(items, 100.percent())
                            .WithEmptyMessage(() => 
                                BackgroundArea(
                                    Card(TextBlock("Empty list").Padding(16.px()))
                                ).WidthStretch().HeightStretch().MinHeight(100.px()));

        // Render the component and append to document body
        document.body.appendChild(itemsList.Render());
    }
}

# ItemsList with Multiple Columns (Grid Layout)

This sample shows how to render an ItemsList using multiple column widths to achieve a grid layout.

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

public class GridItemsListExample
{
    public static void Main()
    {
        // Create a larger set of items
        var items = new IComponent[]
        {
            Card(TextBlock("Item 1")).MinWidth(200.px()),
            Card(TextBlock("Item 2")).MinWidth(200.px()),
            Card(TextBlock("Item 3")).MinWidth(200.px()),
            Card(TextBlock("Item 4")).MinWidth(200.px())
        };

        // Creating ItemsList with 4 columns to arrange items in a grid
        var gridList = ItemsList(items, 25.percent(), 25.percent(), 25.percent(), 25.percent())
                           .WithEmptyMessage(() => 
                               BackgroundArea(
                                   Card(TextBlock("No items found").Padding(16.px()))
                               ).WidthStretch().HeightStretch().MinHeight(100.px()));

        // Render and attach the grid list to the document body
        document.body.appendChild(gridList.Render());
    }
}

# See Also

VirtualizedList – For handling larger sets of items efficiently.
Grid – Related layout component used in multi-column scenarios.
Stack – Alternative layout when using a single column display.