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

items-list-sample.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Transpose.Core;
using Tesserae;
using static Transpose.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();
        }
    }
}

API reference

class

ItemsList

public sealed class ItemsList : IComponent, ISpecialCaseStyling

A simple, non-virtualised vertical list of arbitrary items, used when a DetailsList{T} would be overkill.

Namespace: Tesserae
Implements: IComponent, ISpecialCaseStyling

Constructors

Name	Description
ItemsList	Initializes a new instance of this class.

Constructor

ItemsList

Overload
ItemsList(IComponent[], UnitSize[])	Initializes a new instance of this class.
ItemsList(ObservableList<IComponent>, UnitSize[])	Initializes a new instance of this class.

ItemsList(IComponent[], UnitSize[])

public ItemsList(IComponent[] items, params UnitSize[] columns) : this(new ObservableList<IComponent>(initialValues: items ?? new IComponent[0]), columns)

Initializes a new instance of this class.

Parameters

items IComponent[]
columns UnitSize[]

ItemsList(ObservableList<IComponent>, UnitSize[])

public ItemsList(ObservableList<IComponent> items, params UnitSize[] columns)

Initializes a new instance of this class.

Parameters

items ObservableList<IComponent>
columns UnitSize[]

Properties

Name	Description
Items	Adds the given items to the component.
StylingContainer	Gets or sets the styling container.
PropagateStylesToWrapper	Gets whether a sizing helper applied to this component should tag it so a wrapper-building container hoists the style onto the wrapper.

Property

ItemsList.Items

public ObservableList<IComponent> Items { get; }

Adds the given items to the component.

Property

ItemsList.StylingContainer

public HTMLElement StylingContainer

Gets or sets the styling container.

Property

ItemsList.PropagateStylesToWrapper

public bool PropagateStylesToWrapper

Gets whether a sizing helper applied to this component should tag it so a wrapper-building container hoists the style onto the wrapper.

Methods

Name	Description
WithEmptyMessage	Returns the component configured with the given empty message.
Render	Renders the component's root HTML element.

Method

ItemsList.WithEmptyMessage

public ItemsList WithEmptyMessage(Func<IComponent> emptyListMessageGenerator)

Returns the component configured with the given empty message.

Method

ItemsList.Render

public HTMLElement Render()

Renders the component's root HTML element.

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.cs

using System.Linq;
using Transpose.Core;
using Tesserae;
using static Transpose.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).Foreground(Theme.Primary.Background),
                    VStack().PL(8).Children(
                        TextBlock($"Contact {n}").SemiBold(),
                        TextBlock($"contact{n}@example.com").Small().Secondary()
                    )
                ).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.cs

using System.Linq;
using Transpose.Core;
using Tesserae;
using static Transpose.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().Foreground(Theme.Primary.Background),
                    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.cs

using System;
using Transpose.Core;
using Tesserae;
using static Transpose.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().JustifyContent(ItemJustify.Center).Children(
                        Icon(UIcons.Inbox).XXLarge().Foreground(Theme.Secondary.Foreground),
                        TextBlock("Nothing here yet").SemiBold().PT(8),
                        TextBlock("Create your first item to get started").Small().Secondary(),
                        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);
        }
    }
}

ItemsList

Description

Usage

API reference

Constructors

ItemsList

ItemsList(IComponent[], UnitSize[])

Parameters

ItemsList(ObservableList<IComponent>, UnitSize[])

Parameters

Properties

ItemsList.Items

ItemsList.StylingContainer

ItemsList.PropagateStylesToWrapper

Methods

ItemsList.WithEmptyMessage

ItemsList.Render

Samples

Basic ItemsList with Single Column

Multi-column Grid Layout with Varied Widths

Empty-state Customization

See Also