Tesserae - Searchable List

SearchableList

Description

The SearchableList component is a generic list container designed to display and filter a collection of items that implement the ISearchableItem interface. It provides an integrated search box that allows users to search through the items by typing in a term. The component is highly customizable, supporting features such as custom "no results" messages, background search operations, and the addition of custom components before or after the search box. Use this component when you need a searchable list interface in your application.

Usage

Instantiate a SearchableList using the static helper methods from Tesserae.UI. It accepts an array or an ObservableList of items (each implementing ISearchableItem) and optional column widths for layout purposes. The search box filters items based on whether their IsMatch method returns true for each entered search term.

Below is a minimal sample demonstrating how to implement the ISearchableItem interface and create a SearchableList with a custom "no results" message:

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

    public class MySearchableItem : ISearchableItem
    {
        private readonly string _name;
        public MySearchableItem(string name)
        {
            _name = name;
        }

        public bool IsMatch(string searchTerm) => _name.IndexOf(searchTerm, StringComparison.OrdinalIgnoreCase) >= 0;

        public IComponent Render() => Card(TextBlock(_name));
    }

    public class SampleUsage : IComponent
    {
        public HTMLElement Render()
        {
            // Create an array of searchable items.
            var items = new MySearchableItem[]
            {
                new MySearchableItem("Apple"),
                new MySearchableItem("Banana"),
                new MySearchableItem("Cherry")
            };

            // Instantiate SearchableList with a custom no results message.
            var searchableList = SearchableList(items)
                .WithNoResultsMessage(() => Card(TextBlock("No Results").Padding(16.px())));

            return searchableList.Render();
        }
    }
}

API reference

class

SearchableList<T>

public class SearchableList<T> : IComponent, ISpecialCaseStyling where T : ISearchableItem

A searchable, scrollable list whose items are filtered live as the user types into a built-in search box.

Constructors

Constructor

SearchableList

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

Initializes a new instance of this class.

Constructor

SearchableList

public SearchableList(ObservableList<T> items, params UnitSize[] columns)

Initializes a new instance of this class.

Properties

Property

SearchableList.StylingContainer

public HTMLElement StylingContainer

Gets or sets the styling container.

Property

SearchableList.PropagateToStackItemParent

public bool PropagateToStackItemParent

Gets or sets the propagate to stack item parent.

Property

SearchableList.Items

public ObservableList<T> Items { get; }

Adds the given items to the component.

Property

SearchableList.ShowNotMatchingItems

public bool ShowNotMatchingItems { get; set; }

Shows the not matching items.

Methods

Method

SearchableList.WithNoResultsMessage

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

Returns the component configured with the given no results message.

Method

SearchableList.CaptureSearchBox

public SearchableList<T> CaptureSearchBox(out SearchBox sb)

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

Method

SearchableList.SetKeyboardShortcut

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

Sets the keyboard shortcut of the component.

Method

SearchableList.WithBackgroundSearch

public SearchableList<T> WithBackgroundSearch(Func<string, Task<T[]>> searcher)

Returns the component configured with the given background search.

Method

SearchableList.HideSearchBoxIfLessThan

public SearchableList<T> HideSearchBoxIfLessThan(int items)

Hides the search box if less than.

Method

SearchableList.ShowNotMatching

public SearchableList<T> ShowNotMatching()

Shows the not matching.

Method

SearchableList.BeforeSearchBox

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

Adds the given components before the inline search box.

Method

SearchableList.AfterSearchBox

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

Adds the given components after the inline search box.

Method

SearchableList.Virtualize

public SearchableList<T> Virtualize(UnitSize itemHeight)

Configures the component to virtualize.

Method

SearchableList.Render

public dom.HTMLElement Render()

Renders the component's root HTML element.

Method

SearchableList.WithPagination

public SearchableList<T> WithPagination(int pageSize)

Returns the component configured with the given pagination.

interface

ISearchableItem

public interface ISearchableItem

Samples

Live Filtering with 50 Items

This sample produces 50 contact-style rows. Typing in the search box (try 7, Eve, or manager) filters the list as you type — when nothing matches, the custom "No Results" component is shown.

searchable-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 LiveFilterSample());
        }
    }

    public class LiveFilterSample : IComponent
    {
        public HTMLElement Render()
        {
            var roles = new[] { "Engineer", "Designer", "Manager", "Analyst" };
            var names = new[] { "Alice", "Bob", "Carol", "Dan", "Eve", "Frank", "Grace", "Hank" };

            var items = Enumerable.Range(1, 50).Select(n =>
                new Contact(
                    $"{names[n % names.Length]} #{n}",
                    roles[n % roles.Length],
                    $"user{n}@example.com")
            ).ToArray();

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

    public class Contact : ISearchableItem
    {
        private readonly string _name, _role, _email;
        public Contact(string name, string role, string email)
        { _name = name; _role = role; _email = email; }

        public bool IsMatch(string term)
            => _name.IndexOf(term, StringComparison.OrdinalIgnoreCase) >= 0
            || _role.IndexOf(term, StringComparison.OrdinalIgnoreCase) >= 0
            || _email.IndexOf(term, StringComparison.OrdinalIgnoreCase) >= 0;

        public IComponent Render() => Card(HStack().AlignItemsCenter().Children(
            Icon(UIcons.User).Primary(),
            VStack().PL(12).Children(
                TextBlock(_name).SemiBold(),
                HStack().Children(
                    TextBlock(_role).Small().Muted(),
                    TextBlock(" · " + _email).Small().Muted()
                )
            )
        ).Padding(8.px()));
    }
}

Searchable List with Background Search

WithBackgroundSearch lets you augment the local matches with results fetched asynchronously (for example from a backend). The delegate is invoked with the current search term after the user pauses typing, and its results are merged into the displayed list.

searchable-list-3-sample.js

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

    public class BackgroundSearchSample : IComponent
    {
        public HTMLElement Render()
        {
            var localItems = new[]
            {
                new ColorItem("Crimson"),
                new ColorItem("Coral"),
                new ColorItem("Cerulean")
            };

            return SearchableList(localItems)
                .BeforeSearchBox(Button("Filter").SetIcon(UIcons.Filter).Link())
                .AfterSearchBox(Button("Add color").SetIcon(UIcons.Plus).Primary()
                    .OnClick((s, e) => Toast().Information("Add clicked")))
                .WithBackgroundSearch(async term =>
                {
                    await Task.Delay(500); // simulate remote lookup
                    if (string.IsNullOrWhiteSpace(term)) return new ColorItem[0];
                    return new[]
                    {
                        new ColorItem($"Remote – {term} light"),
                        new ColorItem($"Remote – {term} dark")
                    };
                })
                .WithNoResultsMessage(() =>
                    BackgroundArea(Card(TextBlock("No matching colors").Padding(16.px()))).WS().HS().MinHeight(100.px()))
                .Height(320.px())
                .Render();
        }
    }

    public class ColorItem : ISearchableItem
    {
        private readonly string _name;
        public ColorItem(string name) { _name = name; }
        public bool IsMatch(string term)
            => _name.IndexOf(term, StringComparison.OrdinalIgnoreCase) >= 0;
        public IComponent Render() => Card(TextBlock(_name).Padding(8.px()));
    }
}

SearchableList

Description

Usage

API reference

Constructors

SearchableList

SearchableList

Properties

SearchableList.StylingContainer

SearchableList.PropagateToStackItemParent

SearchableList.Items

SearchableList.ShowNotMatchingItems

Methods

SearchableList.WithNoResultsMessage

SearchableList.SearchBox

SearchableList.CaptureSearchBox

SearchableList.SetKeyboardShortcut

SearchableList.WithBackgroundSearch

SearchableList.HideSearchBoxIfLessThan

SearchableList.ShowNotMatching

SearchableList.BeforeSearchBox

SearchableList.AfterSearchBox

SearchableList.Virtualize

SearchableList.Render

SearchableList.WithPagination

Samples

Live Filtering with 50 Items

Searchable List with Background Search

See also