Tesserae - Searchable Grouped List

SearchableGroupedList

Description

SearchableGroupedList is a versatile collection component designed to render a list of items that can be grouped and searched. It provides built-in search functionality to filter items based on input terms and organizes them by their respective groups. Use this component when you need to display a categorized list that supports live searching over a finite set of items. It is part of the Collections group in the UI toolkit.

Usage

Create a SearchableGroupedList by providing an array or an observable list of items that implement the ISearchableGroupedItem interface, along with a function to generate a header component for each group. The component includes a search box that filters items in real time, and you can further customize its behavior, such as adding custom content before or after the search box or setting a custom “no results” message.

Below is an example of how to instantiate the component:

searchable-grouped-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 sampleComponent = new MySearchableGroupedListSample();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class MySearchableGroupedListSample : IComponent
    {
        public HTMLElement Render()
        {
            // Sample items must implement ISearchableGroupedItem.
            var items = new SearchableGroupedListItem[]
            {
                new SearchableGroupedListItem("Apple", "Fruits"),
                new SearchableGroupedListItem("Broccoli", "Vegetables"),
                new SearchableGroupedListItem("Banana", "Fruits"),
                new SearchableGroupedListItem("Carrot", "Vegetables")
            };

            // Create the list with a header generator for groups.
            var groupedList = SearchableGroupedList(items, groupName =>
                HorizontalSeparator(TextBlock(groupName).Primary().SemiBold()).Left())
             // Optional: add a custom message if no results match the search.
             .WithNoResultsMessage(() =>
                BackgroundArea(Card(TextBlock("No Results Found").Padding(16.px()))).WidthStretch().HeightStretch().MinHeight(100.px()));

            return groupedList.Render();
        }
    }

    public class SearchableGroupedListItem : ISearchableGroupedItem
    {
        private readonly string _value;
        private readonly IComponent _component;

        public SearchableGroupedListItem(string value, string group)
        {
            _value = value;
            _component = Card(TextBlock(value).NonSelectable());
            Group = group;
        }

        // Searches both on the item's value and the group name.
        public bool IsMatch(string searchTerm) =>
            _value.ToLower().Contains(searchTerm.ToLower()) || Group.ToLower().Contains(searchTerm.ToLower());

        public string Group { get; }

        public IComponent Render() => _component;
    }
}

API reference

class

SearchableGroupedList<T>

public class SearchableGroupedList<T> : IComponent, ISpecialCaseStyling where T : ISearchableGroupedItem

A searchable, scrollable list whose items are organized into named groups.

Constructors

Constructor

SearchableGroupedList

public SearchableGroupedList(T[] items, Func<string, IComponent> groupedItemHeaderGenerator, params UnitSize[] columns) : this(new ObservableList<T>(initialValues: items ?? new T[0]), groupedItemHeaderGenerator, columns)

Initializes a new instance of this class.

Constructor

SearchableGroupedList

public SearchableGroupedList(ObservableList<T> originalItems, Func<string, IComponent> groupedItemHeaderGenerator, params UnitSize[] columns)

Initializes a new instance of this class.

Properties

Property

SearchableGroupedList.StylingContainer

public HTMLElement StylingContainer

Gets or sets the styling container.

Property

SearchableGroupedList.PropagateToStackItemParent

public bool PropagateToStackItemParent

Gets or sets the propagate to stack item parent.

Property

SearchableGroupedList.Items

public ObservableList<IComponent> Items { get; }

Adds the given items to the component.

Methods

Method

SearchableGroupedList.WithNoResultsMessage

public SearchableGroupedList<T> WithNoResultsMessage(Func<IComponent> emptyListMessageGenerator)

Returns the component configured with the given no results message.

Method

SearchableGroupedList.WithGroupOrdering

public SearchableGroupedList<T> WithGroupOrdering(IComparer<string> groupComparer)

Returns the component configured with the given group ordering.

Method

SearchableGroupedList.CaptureSearchBox

public SearchableGroupedList<T> CaptureSearchBox(out SearchBox sb)

Captures the inline search box into the supplied variable for later reference.

Method

SearchableGroupedList.SetKeyboardShortcut

public SearchableGroupedList<T> SetKeyboardShortcut(params string[] keys)

Sets the keyboard shortcut of the component.

Method

SearchableGroupedList.BeforeSearchBox

public SearchableGroupedList<T> BeforeSearchBox(params IComponent[] beforeComponents)

Adds the given components before the inline search box.

Method

SearchableGroupedList.AfterSearchBox

public SearchableGroupedList<T> AfterSearchBox(params IComponent[] afterComponents)

Adds the given components after the inline search box.

Method

SearchableGroupedList.Virtualize

public SearchableGroupedList<T> Virtualize(UnitSize itemHeight)

Configures the component to virtualize.

Method

SearchableGroupedList.Render

public HTMLElement Render()

Renders the component's root HTML element.

Method

SearchableGroupedList.WithPagination

public SearchableGroupedList<T> WithPagination(int pageSize)

Returns the component configured with the given pagination.

interface

ISearchableGroupedItem

public interface ISearchableGroupedItem : ISearchableItem

Samples

Live-filtered Grouped List

This sample uses a dataset of 30 produce items spread across four groups. Type any term in the search box (for example "berry", "leaf", or "Fruits") and watch the list filter in real time — both the item name and the group name participate in matching.

searchable-grouped-list-2-sample.js

using System;
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()
        {
            document.body.style.overflow = "hidden";
            MountCenteredToBody(new GroupedSample());
        }
    }

    public class GroupedSample : IComponent
    {
        private static readonly (string Name, string Group)[] _data = new[]
        {
            ("Apple", "Fruits"), ("Banana", "Fruits"), ("Cherry", "Fruits"), ("Date", "Fruits"),
            ("Elderberry", "Fruits"), ("Fig", "Fruits"), ("Grape", "Fruits"), ("Kiwi", "Fruits"),
            ("Mango", "Fruits"), ("Orange", "Fruits"),
            ("Carrot", "Vegetables"), ("Broccoli", "Vegetables"), ("Spinach", "Vegetables"),
            ("Kale", "Vegetables"), ("Lettuce", "Vegetables"), ("Pepper", "Vegetables"),
            ("Tomato", "Vegetables"), ("Onion", "Vegetables"),
            ("Almond", "Nuts"), ("Cashew", "Nuts"), ("Hazelnut", "Nuts"), ("Pecan", "Nuts"),
            ("Walnut", "Nuts"),
            ("Basil", "Herbs"), ("Cilantro", "Herbs"), ("Mint", "Herbs"), ("Oregano", "Herbs"),
            ("Parsley", "Herbs"), ("Rosemary", "Herbs"), ("Thyme", "Herbs")
        };

        public HTMLElement Render()
        {
            var items = _data.Select(d => new GroupedItem(d.Name, d.Group)).ToArray();

            return SearchableGroupedList(items,
                    g => HorizontalSeparator(TextBlock(g).Primary().SemiBold()).Left())
                .WithNoResultsMessage(() =>
                    BackgroundArea(VStack().AlignItemsCenter().Children(
                        Icon(UIcons.SearchMinus).XLarge().Muted(),
                        TextBlock("No matching items").SemiBold().PT(8),
                        TextBlock("Try a different search term").Small().Muted()
                    ).Padding(16.px())).WS().HS().MinHeight(150.px()))
                .Height(400.px())
                .Render();
        }
    }

    public class GroupedItem : ISearchableGroupedItem
    {
        private readonly string _name;
        public GroupedItem(string name, string group) { _name = name; Group = group; }
        public string Group { get; }
        public bool IsMatch(string term)
            => _name.IndexOf(term, StringComparison.OrdinalIgnoreCase) >= 0
            || Group.IndexOf(term, StringComparison.OrdinalIgnoreCase) >= 0;
        public IComponent Render() => Card(TextBlock(_name).NonSelectable());
    }
}

Custom Group Ordering and Commands

WithGroupOrdering lets you control the display order of groups regardless of the order items arrive in. This sample also adds Filter and Add buttons around the search box, and uses a grid layout (three columns) for compact display.

searchable-grouped-list-3-sample.js

using System;
using System.Collections.Generic;
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()
        {
            document.body.style.overflow = "hidden";
            MountCenteredToBody(new AdvancedGroupedSample());
        }
    }

    public class AdvancedGroupedSample : IComponent
    {
        public HTMLElement Render()
        {
            var items = Enumerable.Range(1, 24).Select(n =>
                new GroupedItem($"Task #{n:D2}",
                    (n % 3 == 0) ? "High" : (n % 2 == 0) ? "Medium" : "Low")).ToArray();

            // Order groups High → Medium → Low instead of alphabetical
            var priorityOrder = new Dictionary<string, int> { { "High", 0 }, { "Medium", 1 }, { "Low", 2 } };

            return SearchableGroupedList(items,
                    g => HorizontalSeparator(TextBlock(g).Primary().SemiBold()).Left(),
                    33.percent(), 33.percent(), 34.percent())
                .WithGroupOrdering(Comparer<string>.Create((a, b) => priorityOrder[a].CompareTo(priorityOrder[b])))
                .BeforeSearchBox(Button("Filter").SetIcon(UIcons.Filter).Link())
                .AfterSearchBox(Button("Add Task").SetIcon(UIcons.Plus).Primary()
                    .OnClick((s, e) => Toast().Information("Add task clicked")))
                .Height(420.px())
                .Render();
        }
    }

    public class GroupedItem : ISearchableGroupedItem
    {
        private readonly string _name;
        public GroupedItem(string name, string group) { _name = name; Group = group; }
        public string Group { get; }
        public bool IsMatch(string term)
            => _name.IndexOf(term, StringComparison.OrdinalIgnoreCase) >= 0
            || Group.IndexOf(term, StringComparison.OrdinalIgnoreCase) >= 0;
        public IComponent Render() => Card(TextBlock(_name).NonSelectable());
    }
}

Referenced by

Searchable List

SearchableGroupedList

Description

Usage

API reference

Constructors

SearchableGroupedList

SearchableGroupedList

Properties

SearchableGroupedList.StylingContainer

SearchableGroupedList.PropagateToStackItemParent

SearchableGroupedList.Items

Methods

SearchableGroupedList.WithNoResultsMessage

SearchableGroupedList.WithGroupOrdering

SearchableGroupedList.SearchBox

SearchableGroupedList.CaptureSearchBox

SearchableGroupedList.SetKeyboardShortcut

SearchableGroupedList.BeforeSearchBox

SearchableGroupedList.AfterSearchBox

SearchableGroupedList.Virtualize

SearchableGroupedList.Render

SearchableGroupedList.WithPagination

Samples

Live-filtered Grouped List

Custom Group Ordering and Commands

See also

Referenced by