Tesserae

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:

items-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 sample = new ItemsListExample();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sample);
        }
    }

    public class ItemsListExample : IComponent
    {
        public HTMLElement Render()
        {
            // 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()));

            return list.Render();
        }
    }
}

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.

items-list-2-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()
        {
            new BasicItemsListExample().Run();
        }
    }

    public class BasicItemsListExample
    {
        public void Run()
        {
            // 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
            var sampleComponent = itemsList;
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }
}

ItemsList with Multiple Columns (Grid Layout)

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

items-list-3-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()
        {
            new GridItemsListExample().Run();
        }
    }

    public class GridItemsListExample
    {
        public void Run()
        {
            // 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
            var sampleComponent = gridList;
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }
}