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();
}
}
}
API reference
class
ItemsList
public sealed class ItemsList : IComponent, ISpecialCaseStyling
A simple, non-virtualised vertical list of arbitrary items, used when a would be
overkill.
Constructors
Constructor
ItemsList
public ItemsList(IComponent[] items, params UnitSize[] columns) : this(new ObservableList<IComponent>(initialValues: items ?? new IComponent[0]), columns)
Initializes a new instance of this class.
Constructor
ItemsList
public ItemsList(ObservableList<IComponent> items, params UnitSize[] columns)
Initializes a new instance of this class.
Properties
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.PropagateToStackItemParent
public bool PropagateToStackItemParent
Gets or sets the propagate to stack item parent.
Methods
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.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);
}
}
}
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.
