Tesserae - Picker

Picker

Description

Picker is a versatile UI component used for selecting items from a list of suggestions. It provides support for both multi-selection (with tag-like selections) and single selection modes, and it can render selected items either inline or as separate components. This component is useful when you need to allow users to search, filter, and pick recipients or tags with confirmation feedback via suggestions.

Usage

You instantiate a Picker using the static helper method from Tesserae.UI. The component is generic (Picker) and expects a type that implements the IPickerItem interface. Items can be added using the Items methods, and you can register a callback for when an item is selected using OnItemSelected.

Below is a simple example demonstrating how to create a picker with text suggestions:

picker-sample.cs

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()
        {
            new PickerExample().Run();
        }
    }

    public class SimplePickerItem : IPickerItem
    {
        public SimplePickerItem(string name)
        {
            Name = name;
        }

        public string Name { get; }
        public bool IsSelected { get; set; }

        public IComponent Render()
        {
            return TextBlock(Name);
        }
    }

    public class PickerExample
    {
        public void Run()
        {
            var picker = Picker<SimplePickerItem>(maximumAllowedSelections: 3, duplicateSelectionsAllowed: false)
                .Items(new SimplePickerItem("Item 1"), new SimplePickerItem("Item 2"), new SimplePickerItem("Item 3"))
                .OnItemSelected((sender, e) =>
                {
                    // Handle item selection
                    console.log("Selected: " + e.Item.Name);
                });

            // Render the component and attach it to the DOM
            var sampleComponent = picker;
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }
}

API reference

class

Picker<TPickerItem>

public sealed class Picker<TPickerItem> : IComponent, ITabIndex, IObservableListComponent<TPickerItem>, IRoundedStyle where TPickerItem : class, IPickerItem

A multi-select input that lets the user pick one or more typed items from a dropdown, with optional async loading and free-text entry.

Namespace: Tesserae
Implements: IComponent, ITabIndex, IObservableListComponent<TPickerItem>, IRoundedStyle

Constructors

Name	Description
Picker	Initializes a new instance of this class.

Constructor

Picker

public Picker(int maximumAllowedSelections = int.MaxValue, bool duplicateSelectionsAllowed = false, int suggestionsTolerance = 0, bool renderSelectionsInline = true, string suggestionsTitleText = null)

Initializes a new instance of this class.

Properties

Name	Description
TabIndex	Sets the keyboard tab order of the component.
PickerItems	Gets or sets the picker items.
SelectedPickerItems	Gets or sets the selected picker items.
UnselectedPickerItems	Gets or sets the unselected picker items.
MaximumAllowedSelections	Gets or sets the maximum allowed selections.
DuplicateSelectionsAllowed	Gets or sets the duplicate selections allowed.
SuggestionsTolerance	Gets or sets the suggestions tolerance.

Property

Picker.TabIndex

public int TabIndex { set ; }

Sets the keyboard tab order of the component.

Property

Picker.PickerItems

public IEnumerable<TPickerItem> PickerItems

Gets or sets the picker items.

Property

Picker.SelectedPickerItems

public IEnumerable<TPickerItem> SelectedPickerItems

Gets or sets the selected picker items.

Property

Picker.UnselectedPickerItems

public IEnumerable<TPickerItem> UnselectedPickerItems

Gets or sets the unselected picker items.

Property

Picker.MaximumAllowedSelections

public int? MaximumAllowedSelections { get; }

Gets or sets the maximum allowed selections.

Property

Picker.DuplicateSelectionsAllowed

public bool DuplicateSelectionsAllowed { get; }

Gets or sets the duplicate selections allowed.

Property

Picker.SuggestionsTolerance

public int SuggestionsTolerance { get; }

Gets or sets the suggestions tolerance.

Methods

Name	Description
AsObservable	Returns the component's state as a(n) observable.
Items	Adds the given items to the component.
OnItemSelected	Registers a callback invoked when the item selected event fires.
Render	Renders the component's root HTML element.

Method

Picker.AsObservable

public IObservable<IReadOnlyList<TPickerItem>> AsObservable()

Returns the component's state as a(n) observable.

Method

Picker.Items

Overload
Items(TPickerItem[])	Adds the given items to the component.
Items(IEnumerable<TPickerItem>)	Adds the given items to the component.

Items(TPickerItem[])

public Picker<TPickerItem> Items(params TPickerItem[] items)

Adds the given items to the component.

Parameters

items TPickerItem[]

Items(IEnumerable<TPickerItem>)

public Picker<TPickerItem> Items(IEnumerable<TPickerItem> items)

Adds the given items to the component.

Parameters

items IEnumerable<TPickerItem>

Method

Picker.OnItemSelected

public Picker<TPickerItem> OnItemSelected(ComponentEventHandler<Picker<TPickerItem>, ItemPickedEvent> eventHandler)

Registers a callback invoked when the item selected event fires.

Method

Picker.Render

public HTMLElement Render()

Renders the component's root HTML element.

Samples

Basic Picker with Text Suggestions

In this sample, we create a picker that supports multiple selections. We add a few sample items and register an event handler to log the selected item to the console.

picker-2-sample.cs

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()
        {
            new PickerUsageSample().Run();
        }
    }

    public class CustomPickerItem : IPickerItem
    {
        public CustomPickerItem(string name)
        {
            Name = name;
        }

        public string Name { get; }
        public bool IsSelected { get; set; }

        public IComponent Render()
        {
            return TextBlock(Name);
        }
    }

    public class PickerUsageSample
    {
        public void Run()
        {
            var picker = Picker<CustomPickerItem>(maximumAllowedSelections: 5, duplicateSelectionsAllowed: false, suggestionsTolerance: 1, suggestionsTitleText: "Suggested Items")
                .Items(
                    new CustomPickerItem("Alpha"),
                    new CustomPickerItem("Beta"),
                    new CustomPickerItem("Gamma"),
                    new CustomPickerItem("Delta")
                )
                .OnItemSelected((sender, e) =>
                {
                    // Handle selection - for instance, log to console
                    console.log("Selected Item: " + e.Item.Name);
                });

            // Attach the picker to the DOM
            var sampleComponent = picker;
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }
}

Picker with Inline Selections and Component-based Rendering

This sample demonstrates a picker that renders selected items using an icon alongside text for a richer UI experience.

picker-3-sample.cs

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()
        {
            new ComponentPickerExample().Run();
        }
    }

    public class IconPickerItem : IPickerItem
    {
        private readonly UIcons _icon;

        public IconPickerItem(string name, UIcons icon)
        {
            Name = name;
            _icon = icon;
        }

        public string Name { get; }
        public bool IsSelected { get; set; }

        public IComponent Render()
        {
            return HStack().AlignContent(ItemAlign.Center)
                           .Children(Icon(_icon).MinWidth(16.px()), TextBlock(Name));
        }
    }

    public class ComponentPickerExample
    {
        public void Run()
        {
            var picker = Picker<IconPickerItem>(maximumAllowedSelections: 3, duplicateSelectionsAllowed: false, suggestionsTolerance: 1, renderSelectionsInline: false, suggestionsTitleText: "Select an Item")
                .Items(
                    new IconPickerItem("Option A", UIcons.Bomb),
                    new IconPickerItem("Option B", UIcons.BlenderPhone),
                    new IconPickerItem("Option C", UIcons.Carrot)
                )
                .OnItemSelected((sender, e) =>
                {
                    console.log("User picked: " + e.Item.Name);
                });

            var sampleComponent = picker;
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }
}

Picker

Description

Usage

API reference

Constructors

Picker

Properties

Picker.TabIndex

Picker.PickerItems

Picker.SelectedPickerItems

Picker.UnselectedPickerItems

Picker.MaximumAllowedSelections

Picker.DuplicateSelectionsAllowed

Picker.SuggestionsTolerance

Methods

Picker.AsObservable

Picker.Items

Items(TPickerItem[])

Parameters

Items(IEnumerable<TPickerItem>)

Parameters

Picker.OnItemSelected

Picker.Render

Samples

Basic Picker with Text Suggestions

Picker with Inline Selections and Component-based Rendering

See also