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 renders 12 cards stacked vertically. With a single column width (100%) ItemsList uses a stack layout; the container scrolls when the items exceed the visible area.

items-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()
        {
            var items = Enumerable.Range(1, 12).Select(n =>
                (IComponent)Card(HStack().AlignItemsCenter().Children(
                    Icon(UIcons.User).Primary(),
                    VStack().PL(8).Children(
                        TextBlock($"Contact {n}").SemiBold(),
                        TextBlock($"contact{n}@example.com").Small().Muted()
                    )
                ).Padding(8.px()))
            ).ToArray();

            var list = ItemsList(items, 100.percent()).Height(320.px());

            document.body.style.overflow = "hidden";
            MountCenteredToBody(list);
        }
    }
}

Multi-column Grid Layout with Varied Widths

Passing multiple column widths switches the layout to a grid. Mixing fixed and fractional widths shows how ItemsList handles responsive sizing.

items-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()
        {
            var items = Enumerable.Range(1, 18).Select(n =>
                (IComponent)Card(VStack().AlignItemsCenter().Children(
                    Icon(UIcons.Picture).XLarge().Primary(),
                    TextBlock($"Tile {n}").SemiBold().PT(8)
                ).Padding(12.px())).MinWidth(120.px())
            ).ToArray();

            // 3-column grid with mixed proportions (narrow / wide / narrow)
            var list = ItemsList(items, 25.percent(), 50.percent(), 25.percent()).Height(360.px());

            document.body.style.overflow = "hidden";
            MountCenteredToBody(list);
        }
    }
}

Empty-state Customization

When the list contains no items, WithEmptyMessage controls the placeholder. The delegate is rendered inline so it can include any Tesserae component, including action buttons.

items-list-4-sample.js

using System;
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 list = ItemsList(new IComponent[0])
                .WithEmptyMessage(() =>
                    BackgroundArea(VStack().AlignItemsCenter().JustifyContentCenter().Children(
                        Icon(UIcons.InboxEmpty).XXLarge().Muted(),
                        TextBlock("Nothing here yet").SemiBold().PT(8),
                        TextBlock("Create your first item to get started").Small().Muted(),
                        Button("Add item").Primary().SetIcon(UIcons.Plus).MT(16)
                            .OnClick((s, e) => Toast().Information("Add clicked"))
                    ).Padding(24.px())).WS().HS())
                .Height(280.px());

            document.body.style.overflow = "hidden";
            MountCenteredToBody(list);
        }
    }
}