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

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

Methods

• SuppressSelectedOnChangingItemSelections() : Dropdown
  Prevents the component from automatically firing the select event when the item selection changes.

• FitContent() : Dropdown
  Adjusts the Dropdown's appearance to fit the content width.

• Items(params Item[] children) : Dropdown
  Sets the available items for the dropdown. This method replaces any previously rendered options.
  Parameters:
  • children – An array of Dropdown.Item instances, typically created with DropdownItem().

• Items(Func<Task<Item[]>> itemsSource) : Dropdown
  Specifies an asynchronous callback to load available items. The async method is invoked when loading the dropdown items.
  Parameters:
  • itemsSource – A callback returning a Task that produces an array of Dropdown.Item.

• LoadItemsAsync() : Task
  Initiates the asynchronous items retrieval specified by the async Items method. This should be called if you want to explicitly load new data.

• Disabled(bool value = true) : Dropdown
  Enables or disables the component.
  Parameters:
  • value – Set to true to disable the Dropdown.

• NoBorder() : Dropdown
  Removes the border from the dropdown container.

• NoBackground() : Dropdown
  Removes the background styling from the dropdown container.

• Required() : Dropdown
  Marks the dropdown as required; it will display a required state until a valid selection is made.

• Placeholder(string text) : Dropdown
  Sets a textual placeholder when no item is selected.
  Parameters:
  • text – The placeholder text.

• Placeholder(IComponent placeholder) : Dropdown
  Sets a custom component as the placeholder when no selection is made.
  Parameters:
  • placeholder – An IComponent to display when no option is selected.

• Single() : Dropdown
  Configures the dropdown for single-select mode.

• Multi() : Dropdown
  Configures the dropdown for multi-select mode, allowing multiple items to be selected.

• NoArrow() : Dropdown
  Hides the default dropdown arrow icon.

• SetArrowIcon(UIcons icon, TextSize size = TextSize.Small, UIconsWeight weight = UIconsWeight.Regular) : Dropdown
  Sets a custom icon for the dropdown’s arrow.
  Parameters:
  • icon – The custom icon from UIcons.
  • size – (Optional) The text size of the icon.
  • weight – (Optional) The weight of the icon.

• Focus() : Dropdown
  Sets the focus to the dropdown component.

• WithCustomSelectionRender(Func<Item[], IComponent> renderSelectedItems) : Dropdown
  Uses a custom renderer to display selected items when the Dropdown is closed.
  Parameters:
  • renderSelectedItems – A function that takes an array of selected items and returns an IComponent for rendering them.

• Attach(ComponentEventHandler handler)
  Attaches an event handler that is invoked when the dropdown selection changes.
  Parameters:
  • handler – The callback function that receives the Dropdown instance.

Properties

• TabIndex (int)
  Sets the tab index of the Dropdown to control focus order.
  Setter only.

• Mode (Dropdown.SelectMode)
  Gets or sets the selection mode of the dropdown. Use Dropdown.SelectMode.Single for single selection or Dropdown.SelectMode.Multi for multi-selection.

• SelectedItems (Dropdown.Item[])
  Gets the currently selected items as an array.

• SelectedText (string)
  Retrieves a comma-delimited string of the text from the selected items.

• Error (string)
  Gets or sets an error message that is displayed when the dropdown state is invalid.

• HasBorder (bool)
  Gets or sets whether the dropdown container displays a border.

• IsInvalid (bool)
  Gets or sets the invalid state of the dropdown for validation purposes.

• IsEnabled (bool)
  Gets or sets whether the dropdown is enabled.

• IsRequired (bool)
  Gets or sets whether the dropdown is marked as required.

Samples

Basic Dropdown

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

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.

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")
            };
        }
    }
}

See also

• Button
• ChoiceGroup
• Toggle