Tesserae - Auto Complete Box

AutoCompleteBox

Description

AutoCompleteBox is a single-line text input with a list of suggestions that narrows as the user types, and an optional asynchronous check of the typed value. Use it when the good values are known but not closed: model ids a server lists, tags, e-mail domains.

The text stays free. A suggestion is a shortcut, not a constraint. If the value must be one of a list, use a searchable Dropdown instead.

AutoCompleteBox extends Input, so it has the same members as a TextBox: Text, Disabled(), Required(), Validation(...), Bind(...), OnChange(...), OnInput(...) and OnBlur(...).

Usage

Create one with AutoCompleteBox(text) and give it suggestions with Suggestions(...):

Suggestions(params string[]) takes a fixed list.
Suggestions(Func<Task<string[]>>) loads the list once, the first time it is needed (focus or the first keystroke), and caches it. The loader returns everything: the component filters, prefix matches first, then substring matches, case-insensitive.
ReloadSuggestions() drops the cached list.
MaxSuggestions(int) caps the rows shown (default 50).

A pick (click, Enter, or Tab on a highlighted row) sets the text and raises the change event, so one OnChange handler sees a pick and an edit alike. An edit raises it on blur. A read-only box shows no suggestions.

Fixed suggestions

auto-complete-box-sample.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var fruits = new[] { "Apple", "Apricot", "Banana", "Blackberry", "Blueberry", "Cherry", "Grape", "Grapefruit", "Lemon", "Lime", "Mango", "Orange", "Peach", "Pear", "Pineapple", "Plum" };

            var component = Stack().W(320).Children(
                Label("Fruit").SetContent(
                    AutoCompleteBox().SetPlaceholder("Start typing a fruit...").Suggestions(fruits)
                )
            );

            document.body.style.overflow = "hidden";
            MountCenteredToBody(component);
        }
    }
}

Loaded suggestions and an asynchronous check

CheckAsync(check, debounceMilliseconds = 400) runs after each edit, debounced, and once for the initial text. An empty box is not checked. The check returns AutoCompleteCheck.Valid(message, tooltip), Warning(message, tooltip), Invalid(message, tooltip) or None(). The answer is drawn at the end of the box as an icon and a one-line label, which screen readers also announce. While the check runs, the box shows a spinner and "Checking...". An invalid answer also turns the border red. Only the answer for the current text is shown.

Prefer a warning over invalid when the check cannot know every good value. Recheck() runs the check now, and LastCheck holds the last answer.

auto-complete-box-check-sample.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var models = new[]
            {
                "gpt-4.1", "gpt-4.1-mini", "gpt-4o", "gpt-4o-mini", "o3", "o4-mini",
                "claude-opus-4-1", "claude-sonnet-4-5", "claude-haiku-4-5",
                "mistral-large-latest", "mistral-small-latest"
            };

            var component = Stack().W(360).Children(
                Label("Model ID").SetContent(
                    AutoCompleteBox("gpt-4o")
                       .SetPlaceholder("The model id this endpoint answers to")
                       .Suggestions(async () =>
                        {
                            await Task.Delay(600);
                            return models;
                        })
                       .CheckAsync(async text =>
                        {
                            await Task.Delay(500);

                            return models.Contains(text)
                                ? AutoCompleteCheck.Valid("Listed", tooltip: "This endpoint lists the model id.")
                                : AutoCompleteCheck.Warning("Not listed", tooltip: "This endpoint does not list \"" + text + "\".");
                        })
                )
            );

            document.body.style.overflow = "hidden";
            MountCenteredToBody(component);
        }
    }
}

Keyboard

ArrowDown and ArrowUp open the list and move through it. Enter picks the highlighted row. Escape closes the list. Tab moves to the next field, picking the highlighted row first if there is one; with none highlighted the typed text is kept. The input has role="combobox" over a role="listbox".

API reference

class

AutoCompleteBox

public sealed class AutoCompleteBox : Input<AutoCompleteBox>, ITextFormating, IHasBackgroundColor, IHasForegroundColor, IRoundedStyle

A single-line text input that suggests values as the user types and can check the typed value asynchronously. The text stays free: a suggestion is a shortcut, not a constraint, which is what sets it apart from a searchable Dropdown.

Remarks

Suggestions come from a fixed list or from a loader that runs once, on first use, and is cached until ReloadSuggestions; either way they are filtered here, prefix matches first. The check (CheckAsync) runs debounced after every edit and once for the initial text, and only the answer for the text currently in the box is shown. Its result is an icon and a short label at the end of the box (an invalid answer also draws the box's border red), apart from Error and IsInvalid, so a synchronous .Validation(...) on the same box keeps working.

Namespace: Tesserae
Inheritance: Input<AutoCompleteBox> → AutoCompleteBox
Implements: ITextFormating, IHasBackgroundColor, IHasForegroundColor, IRoundedStyle

Constructors

Name	Description
AutoCompleteBox	Creates the box with an optional initial text.

Constructor

AutoCompleteBox

public AutoCompleteBox(string text = string.Empty) : base("text", text)

Creates the box with an optional initial text.

Properties

Name	Description
Placeholder	Gets or sets the placeholder text.
Size	Gets or sets the text size.
Weight	Gets or sets the text weight.
TextAlign	Gets or sets the text alignment.
Background	Gets or sets the background color.
Foreground	Gets or sets the foreground color.
IsReadOnly	Gets or sets whether the box is read-only; a read-only box shows no suggestions.
LastCheck	The answer of the last check that completed for the current text, or `null`.

Property

AutoCompleteBox.Placeholder

public string Placeholder { get ; set ; }

Gets or sets the placeholder text.

Property

AutoCompleteBox.Size

public TextSize Size { get ; set ; }

Gets or sets the text size.

Property

AutoCompleteBox.Weight

public TextWeight Weight { get ; set ; }

Gets or sets the text weight.

Property

AutoCompleteBox.TextAlign

public TextAlign TextAlign { get ; set ; }

Gets or sets the text alignment.

Property

AutoCompleteBox.Background

public string Background { get ; set ; }

Gets or sets the background color.

Property

AutoCompleteBox.Foreground

public string Foreground { get ; set ; }

Gets or sets the foreground color.

Property

AutoCompleteBox.IsReadOnly

public bool IsReadOnly { get ; set ; }

Gets or sets whether the box is read-only; a read-only box shows no suggestions.

Property

AutoCompleteBox.LastCheck

public AutoCompleteCheck LastCheck { get; private set; }

The answer of the last check that completed for the current text, or null.

Methods

Name	Description
SetPlaceholder	Sets the placeholder text.
ReadOnly	Sets the box as read-only.
Suggestions	Sets a fixed list of suggestions, replacing any loader set before.
ReloadSuggestions	Drops the cached answer of the suggestions loader, so the next use loads it again - after a setting the list depends on has changed. Refreshes the list at once if it is open.
MaxSuggestions	Caps how many suggestions the list shows at once. Defaults to 50.
CheckAsync	Checks the text asynchronously after each edit, debounced by `debounceMilliseconds`, and shows the answer as an icon and its message at the end of the box, with the answer's tooltip (if any) over them: `Valid`, `Warning`, `Invalid` (which also draws the box's border red), or `None` for nothing. An empty box is not checked. The initial text is checked straight away.
Recheck	Runs the check now for the current text, without waiting for the debounce.

Method

AutoCompleteBox.SetPlaceholder

public AutoCompleteBox SetPlaceholder(string placeholder)

Sets the placeholder text.

Method

AutoCompleteBox.ReadOnly

public AutoCompleteBox ReadOnly()

Sets the box as read-only.

Method

AutoCompleteBox.Suggestions

Overload
Suggestions(string[])	Sets a fixed list of suggestions, replacing any loader set before.
Suggestions(Func<Task<string[]>>)	Sets a loader for the suggestions. It runs the first time the list is needed (on focus or the first keystroke) and its answer is kept until `ReloadSuggestions`; the component filters it as the user types, so the loader returns everything it has.

Suggestions(string[])

public AutoCompleteBox Suggestions(params string[] suggestions)

Sets a fixed list of suggestions, replacing any loader set before.

Parameters

suggestions string[]

Suggestions(Func<Task<string[]>>)

public AutoCompleteBox Suggestions(Func<Task<string[]>> loader)

Sets a loader for the suggestions. It runs the first time the list is needed (on focus or the first keystroke) and its answer is kept until ReloadSuggestions; the component filters it as the user types, so the loader returns everything it has.

Parameters

loader Func<Task<string[]>>

Method

AutoCompleteBox.ReloadSuggestions

public AutoCompleteBox ReloadSuggestions()

Drops the cached answer of the suggestions loader, so the next use loads it again - after a setting the list depends on has changed. Refreshes the list at once if it is open.

Method

AutoCompleteBox.MaxSuggestions

public AutoCompleteBox MaxSuggestions(int max)

Caps how many suggestions the list shows at once. Defaults to 50.

Method

AutoCompleteBox.CheckAsync

public AutoCompleteBox CheckAsync(Func<string, Task<AutoCompleteCheck>> check, int debounceMilliseconds = 400)

Checks the text asynchronously after each edit, debounced by debounceMilliseconds, and shows the answer as an icon and its message at the end of the box, with the answer's tooltip (if any) over them: Valid, Warning, Invalid (which also draws the box's border red), or None for nothing. An empty box is not checked. The initial text is checked straight away.

Method

AutoCompleteBox.Recheck

public AutoCompleteBox Recheck()

Runs the check now for the current text, without waiting for the debounce.

enum

AutoCompleteCheckState

public enum AutoCompleteCheckState

What an AutoCompleteBox check says about the text in the box.

Namespace: Tesserae

Values

Name	Description
None	Nothing to say; no indicator is shown.
Valid	The value is known to be good.
Warning	The value may be wrong, but is allowed.
Invalid	The value is wrong.

Value

AutoCompleteCheckState.None

None

Nothing to say; no indicator is shown.

Value

AutoCompleteCheckState.Valid

Valid

The value is known to be good.

Value

AutoCompleteCheckState.Warning

Warning

The value may be wrong, but is allowed.

Value

AutoCompleteCheckState.Invalid

Invalid

The value is wrong.

class

AutoCompleteCheck

public sealed class AutoCompleteCheck

The answer of an CheckAsync callback.

Namespace: Tesserae

Properties

Name	Description
State	The verdict.
Message	The short label shown next to the indicator's icon and announced to screen readers, or `null` for the icon alone.
Tooltip	The explanation shown in a tooltip over the indicator, or `null` for none.

Property

AutoCompleteCheck.State

public AutoCompleteCheckState State { get; }

The verdict.

Property

AutoCompleteCheck.Message

public string Message { get; }

The short label shown next to the indicator's icon and announced to screen readers, or null for the icon alone.

Property

AutoCompleteCheck.Tooltip

public string Tooltip { get; }

The explanation shown in a tooltip over the indicator, or null for none.

Methods

Name	Description
None	No verdict: clears the indicator.
Valid	The value is good. Labelled "Verified" unless `message` says otherwise.
Warning	The value may be wrong, but is allowed.
Invalid	The value is wrong; the box's border turns red. Labelled "Not verified" unless `message` says otherwise.

Method

AutoCompleteCheck.None

public static AutoCompleteCheck None()

No verdict: clears the indicator.

Method

AutoCompleteCheck.Valid

public static AutoCompleteCheck Valid(string message = "Verified", string tooltip = null)

The value is good. Labelled "Verified" unless message says otherwise.

Method

AutoCompleteCheck.Warning

public static AutoCompleteCheck Warning(string message, string tooltip = null)

The value may be wrong, but is allowed.

Method

AutoCompleteCheck.Invalid

public static AutoCompleteCheck Invalid(string message = "Not verified", string tooltip = null)

The value is wrong; the box's border turns red. Labelled "Not verified" unless message says otherwise.

AutoCompleteBox

Description

Usage

Fixed suggestions

Loaded suggestions and an asynchronous check

Keyboard

API reference

Constructors

AutoCompleteBox

Properties

AutoCompleteBox.Placeholder

AutoCompleteBox.Size

AutoCompleteBox.Weight

AutoCompleteBox.TextAlign

AutoCompleteBox.Background

AutoCompleteBox.Foreground

AutoCompleteBox.IsReadOnly

AutoCompleteBox.LastCheck

Methods

AutoCompleteBox.SetPlaceholder

AutoCompleteBox.ReadOnly

AutoCompleteBox.Suggestions

Suggestions(string[])

Parameters

Suggestions(Func<Task<string[]>>)

Parameters

AutoCompleteBox.ReloadSuggestions

AutoCompleteBox.MaxSuggestions

AutoCompleteBox.CheckAsync

AutoCompleteBox.Recheck

Values

AutoCompleteCheckState.None

AutoCompleteCheckState.Valid

AutoCompleteCheckState.Warning

AutoCompleteCheckState.Invalid

Properties

AutoCompleteCheck.State

AutoCompleteCheck.Message

AutoCompleteCheck.Tooltip

Methods

AutoCompleteCheck.None

AutoCompleteCheck.Valid

AutoCompleteCheck.Warning

AutoCompleteCheck.Invalid

See also