Dropdown | Curiosity Documentation

# 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.Threading.Tasks;
using H5;
using static H5.Core.dom;
using Tesserae;
using static Tesserae.UI;

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

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

using System;
using H5;
using static H5.Core.dom;
using Tesserae;
using static Tesserae.UI;

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.Threading.Tasks;
using H5;
using static H5.Core.dom;
using Tesserae;
using static Tesserae.UI;

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

# Dropdown