Tesserae - Dropdown

Description

The Dropdown component renders an interactive list of options with a single visible selected item by default. When a user clicks the dropdown, all available options become visible. It supports both single-select and multi-select modes, customizable arrow icons, asynchronous item loading, validation, and styling options such as disabled, required, no-border, or no-background. Use the Dropdown when you want to allow users to choose from a list of items while keeping the UI compact.

Usage

Instantiate a Dropdown component using the static helper method from Tesserae.UI. Items can be provided directly or loaded asynchronously. The following sample demonstrates a basic single-select Dropdown with two options and custom validation logic.

Sample Code

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

    public class DropdownExample : IComponent
    {
        public HTMLElement Render()
        {
            // Create a basic Dropdown with two options
            var dropdown = Dropdown().Items(
                DropdownItem("Option 1").Selected(),
                DropdownItem("Option 2")
            );

            // Example: Attach a custom validation handler.
            dropdown.Attach(dd =>
            {
                if (dd.SelectedItems.Length != 1 || dd.SelectedItems[0].Text != "Option 1")
                {
                    dd.IsInvalid = true;
                    dd.Error = "Please select 'Option 1'";
                }
                else
                {
                    dd.IsInvalid = false;
                }
            });

            return dropdown.Render();
        }
    }
}

API reference

class

Dropdown

public sealed class Dropdown : Layer<Dropdown>, ICanValidate<Dropdown>, IObservableListComponent<Dropdown.Item>, ITabIndex, IRoundedStyle

A select-style form input for picking one or many values from a list, with filtering, async loading and rich item rendering.

Constructors

Properties

Methods

Method

Dropdown.SuppressSelectedOnChangingItemSelections

public Dropdown SuppressSelectedOnChangingItemSelections()

Configures the component to not fire selection-changed callbacks while selections are being mutated in bulk.

Method

Dropdown.LoadItemsAsync

public async Task LoadItemsAsync()

This will initiate the last async data retrieval specified via a call to the Items method overload that takes a Func-of-Task-of-array-of-T. If there has not been call to that method (or if LoadItemsAsync has already been called after it was called) then this will throw an InvalidOperationException. If another async data retrieval had already been initiated but has not completed yet, its results will be ignored when it DOES complete because this call came after it and it is presumed that this data will be more current).

Method

Dropdown.Items

public Dropdown Items(params Item[] children)

This will set items to the available options, replacing any that are already rendered (and meaning that any async data retrievals that have started but not completed yet will be ignored when they DO complete because this call came after it and it is presumed that this data will be more current)

Method

Dropdown.Items

public Dropdown Items(Func<Task<Item[]>> itemsSource)

This will specify an asynchronous callback that describes how to get available options - note that they will not be retrieved until LoadItemsAsync is called (when that successfully gets new item data, any existing items will be removed first and the list will be completely replace with the new data). LoadItemsAsync may be called explicitly (and immediately after setting this) - if not, it will be called automatically when the User clicks to open the dropdown.

Method

Dropdown.EnsureAsyncLoadingStateEnabled

private void EnsureAsyncLoadingStateEnabled()

When a LoadItemsAsync call starts, there should be a spinner to indicate that something is happening in the background - but if a further async request comes in before the previous one has completed then there is no need to change anything as the spinner state will already be enabled. When multiple async requests overlap, which was started later will take precedence and the results of the earlier-started one will be ignored - when the 'winning' request completes, it will call the synchronous Items method and that will ensure that any loading state is disabled.

Method

Dropdown.EnsureAsyncLoadingStateDisabled

private void EnsureAsyncLoadingStateDisabled()

When data is successfully retrieved from a LoadItemsAsync call, it will call the synchronous Items method that will call this and ensure that any spinner state is disabled. This happens in the simple case where there is only that single async retrieval and it runs to completion and it also happens if it is superceded by a more recent LoadItemsAsync call or by a separate synchronous Items call.

Fields

Samples

The following sample demonstrates the creation of a basic single-select Dropdown with two options and a custom validation handler.

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

    public class BasicDropdownSample : IComponent
    {
        public HTMLElement Render()
        {
            // Create a basic Dropdown with two options.
            var dropdown = Dropdown().Items(
                DropdownItem("1-1").Selected(),
                DropdownItem("1-2")
            );

            // Attach a validation handler.
            dropdown.Attach(dd =>
            {
                if (dd.SelectedItems.Length != 1 || dd.SelectedItems[0].Text != "1-1")
                {
                    dd.IsInvalid = true;
                    dd.Error = "Some error happens, need 1-1";
                }
                else
                {
                    dd.IsInvalid = false;
                }
            });

            return dropdown.Render();
        }
    }
}

Asynchronous Items Loading

The next example shows how to configure async item loading for a Dropdown. The items will be loaded after a 5-second delay once the dropdown is opened.

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

    public class AsyncDropdownSample : IComponent
    {
        public HTMLElement Render()
        {
            // Create a Dropdown and specify an async data retrieval callback.
            var dropdown = Dropdown().Items(GetItemsAsync);

            // Optionally, start loading async data immediately.
            dropdown.LoadItemsAsync().FireAndForget();

            return dropdown.Render();
        }

        private async Task<Dropdown.Item[]> GetItemsAsync()
        {
            await Task.Delay(5000); // Simulate network delay
            return new[]
            {
                DropdownItem("Header 1").Header(),
                DropdownItem("1-1"),
                DropdownItem("1-2"),
                DropdownItem("1-3"),
                DropdownItem("1-4").Disabled(),
                DropdownItem("1-5"),
                DropdownItem().Divider(),
                DropdownItem("Header 2").Header(),
                DropdownItem("2-1"),
                DropdownItem("2-2"),
                DropdownItem("2-3"),
                DropdownItem("2-4"),
                DropdownItem("2-5")
            };
        }
    }
}

Description

Usage

Sample Code

API reference

Samples

Asynchronous Items Loading

See also

Referenced by

Dropdown

Description

Usage

Sample Code

API reference

Constructors

Dropdown

Properties

Dropdown.TabIndex

Dropdown.Mode

Dropdown.SelectedItems

Dropdown.SelectedText

Dropdown.Error

Dropdown.HasBorder

Dropdown.IsInvalid

Dropdown.IsEnabled

Dropdown.IsRequired

Methods

Dropdown.SuppressSelectedOnChangingItemSelections

Dropdown.FitContent

Dropdown.Render

Dropdown.Focus

Dropdown.LoadItemsAsync

Dropdown.Show

Dropdown.Hide

Dropdown.Attach

Dropdown.Single

Dropdown.Multi

Dropdown.Searchable

Dropdown.NoArrow

Dropdown.SetArrowIcon

Dropdown.Items

Dropdown.Items

Dropdown.Disabled

Dropdown.NoBorder

Dropdown.NoBackground

Dropdown.Required

Dropdown.Placeholder

Dropdown.Placeholder

Dropdown.WithCustomSelectionRender

Dropdown.AsObservable

Dropdown.EnsureAsyncLoadingStateEnabled

Dropdown.EnsureAsyncLoadingStateDisabled

Fields

Dropdown.GlobalCustomIcon

Samples

Basic Dropdown

Asynchronous Items Loading

See also

Referenced by