PromptPlus

# PromptPlus ## **Select<T> — Methods** [](https://www.nuget.org/packages/PromptPlus) [](https://opensource.org/licenses/MIT) [](https://dotnet.microsoft.com/)

← Back to Home • Next: Select — Operations →

---

Every fluent method on ISelectControl<T>. Each returns the same control instance, so calls chain in any order. Call Run last.

The factory is PromptPlus.Controls.Select<T>(string prompt = "", string? description = null), which returns ISelectControl<T>.

Quick jump: AddItem · AddItems · AddGroupedItem · AddGroupedItems · AddSeparator · Interaction · InteractionAsync · TextSelector · TextSelectorAsync · ExtraInfo · ExtraInfoAsync · HideTipGroup · Filter · AutoSelect · PageSize · Default · UseDefaultHistory · DefaultMatchBy · PredicateSelected · PredicateSelectedAsync · ViewOnly · ChangeDescription · ChangeDescriptionAsync · EnableHistory · Styles · Options · Run

---

Adding items

AddItem

ISelectControl<T> AddItem(T value, bool disable = false)

Adds a single item. Set disable: true to show it grayed out and non-selectable.

PromptPlus.Controls.Select<string>("City")
    .AddItem("Tokyo")
    .AddItem("London", disable: true)   // visible but not selectable
    .Run();

Throws ArgumentNullException if value is null.

---

AddItems

ISelectControl<T> AddItems(IEnumerable<T> values, bool disable = false)

Adds many items at once. disable: true disables all of them.

PromptPlus.Controls.Select<string>("City")
    .AddItems(["Seattle", "London", "Tokyo"])
    .Run();

---

AddGroupedItem

ISelectControl<T> AddGroupedItem(string group, T value, bool disable = false)

Adds one item under a named group header.

---

AddGroupedItems

ISelectControl<T> AddGroupedItems(string group, IEnumerable<T> values, bool disable = false)

Adds many items under a named group header. Items keep their group as they scroll.

PromptPlus.Controls.Select<string>("City")
    .AddGroupedItems("North America", ["Seattle", "New York"])
    .AddGroupedItems("Asia",          ["Tokyo", "Singapore"])
    .Run();

A hint shows the group of the focused item; hide it with HideTipGroup.

---

AddSeparator

ISelectControl<T> AddSeparator(SeparatorLine separatorLine = SeparatorLine.SingleLine, char? value = null)

Inserts a visual divider between items.

SeparatorLine	Renders
SingleLine	A single-line rule (default)
DoubleLine	A double-line rule
UserChar	A row of the character passed in value

PromptPlus.Controls.Select<string>("City")
    .AddItem("Seattle")
    .AddSeparator()                          // single line
    .AddItem("Tokyo")
    .AddSeparator(SeparatorLine.DoubleLine)  // double line
    .AddItem("London")
    .AddSeparator(SeparatorLine.UserChar, '*')
    .AddItem("Other")
    .Run();

Throws ArgumentNullException if separatorLine is SeparatorLine.UserChar and value is null.

---

Loading from a source

Interaction

ISelectControl<T> Interaction<T1>(IEnumerable<T1> items, Action<T1, ISelectControl<T>> interactionAction)

Iterates a source collection and lets you add items programmatically — useful when mapping from a different shape or applying per-item logic.

PromptPlus.Controls.Select<(int id, string City, string other)>("City")
    .Interaction(MyCities(), (row, ctrl) => ctrl.AddItem(row))
    .TextSelector(row => row.City)
    .Run();

---

InteractionAsync

ISelectControl<T> InteractionAsync<T1>(IEnumerable<T1> items, Func<T1, ISelectControl<T>, Task> interactionAction)

Asynchronous version of Interaction, for sources that need awaiting per item.

---

Item text & info

TextSelector

ISelectControl<T> TextSelector(Func<T, string> value)

Sets how each item is rendered as text. By default ToString() is used (and [Display] names for enums). Provide a selector for custom types.

PromptPlus.Controls.Select<User>("User")
    .AddItems(users)
    .TextSelector(u => $"{u.Name} <{u.Email}>")
    .Run();

---

TextSelectorAsync

ISelectControl<T> TextSelectorAsync(Func<T, Task<string>> value)

Asynchronous version of TextSelector.

---

ExtraInfo

ISelectControl<T> ExtraInfo(Func<T, string?> extraInfoNode)

Shows a secondary piece of text for each item (return null to show nothing for that item). It is wrapped with the prefix/suffix from config (default " (" — with a leading space — and ")"). The focused item’s ExtraInfo also appears in the live answer line while navigating (not in the final answer shown after Enter) — see Operations.

PromptPlus.Controls.Select<string>("City")
    .AddItems(["Seattle", "Tokyo"])
    .ExtraInfo(city => $"Length: {city.Length}")
    .Run();

---

ExtraInfoAsync

ISelectControl<T> ExtraInfoAsync(Func<T, Task<string?>> extraInfoNode)

Asynchronous version of ExtraInfo.

---

HideTipGroup

ISelectControl<T> HideTipGroup(bool value = true)

Hides the “current group” hint shown for grouped lists. Default false (hint visible).

---

Filtering & paging

Filter

ISelectControl<T> Filter(FilterMode value)

Controls live filtering as the user types.

FilterMode	Behavior
Disabled	No filtering (default)
Contains	Match items containing the typed text
StartsWith	Match items starting with the typed text

PromptPlus.Controls.Select<string>("City")
    .AddItems(cities)
    .Filter(FilterMode.Contains)
    .Run();

---

AutoSelect

ISelectControl<T> AutoSelect(bool value = true)

When filtering narrows the list to a single selectable item, that item is selected and confirmed automatically — no Enter needed.

PromptPlus.Controls.Select<string>("City")
    .AddItems(["Seattle", "London", "Tokyo"])
    .Filter(FilterMode.StartsWith)
    .AutoSelect()   // typing "T" auto-picks Tokyo
    .Run();

---

PageSize

ISelectControl<T> PageSize(byte value)

Rows visible at once (valid range 0–255). 0 (default) auto-computes from terminal height, reserving lines for the header, footer, and pagination. Values above the available height are clamped.

PromptPlus.Controls.Select<string>("City").AddItems(cities).PageSize(8).Run();

---

Initial value & equality

Default

ISelectControl<T> Default(T value, bool useDefaultHistory = true)

Pre-highlights value. When useDefaultHistory is true and history is enabled, the last history value is preferred. Matching uses DefaultMatchBy if provided, otherwise default equality.

PromptPlus.Controls.Select<string>("City")
    .AddItems(cities)
    .Default("Tokyo")
    .Run();

Throws ArgumentNullException if value is null.

---

UseDefaultHistory

ISelectControl<T> UseDefaultHistory()

Sets the initial selection from the history store (when EnableHistory is set), without also passing an explicit Default.

---

DefaultMatchBy

ISelectControl<T> DefaultMatchBy(Func<T, T, bool> comparer)

Custom equality used to locate the Default item (and to compare items in general) — essential for records/classes where reference equality is not meaningful.

PromptPlus.Controls.Select<(int id, string City, string other)>("City")
    .Interaction(MyCities(), (r, c) => c.AddItem(r))
    .TextSelector(r => r.City)
    .DefaultMatchBy((a, b) => a.id == b.id)
    .Default(new(4, "New York", "any4"))
    .Run();

Throws ArgumentNullException if comparer is null.

---

Validating the confirmed item

Validation runs on Enter. On failure the list stays open and shows an error.

PredicateSelected

ISelectControl<T> PredicateSelected(Func<T, bool> validselect)
ISelectControl<T> PredicateSelected(Func<T, (bool, string?)> validselect)

Overload	Return	Behavior
Func<T, bool>	true = valid	Generic error on failure
Func<T, (bool, string?)>	(isValid, message)	Custom message on failure

PromptPlus.Controls.Select<string>("City")
    .AddItems(["Seattle", "London", "Tokyo"])
    .PredicateSelected(c => c == "Tokyo"
        ? (true, null)
        : (false, "Only Tokyo can be selected"))
    .Run();

---

PredicateSelectedAsync

ISelectControl<T> PredicateSelectedAsync(Func<T, Task<bool>> validselect)
ISelectControl<T> PredicateSelectedAsync(Func<T, Task<(bool, string?)>> validselect)

Asynchronous counterparts.

⚠️ The async predicate is awaited synchronously (blocking) on the UI thread — keep it fast.

---

Read-only display

ViewOnly

ISelectControl<T> ViewOnly(bool value = true)

Renders the list for viewing only — items cannot be selected. Combine with Default to highlight one entry.

PromptPlus.Controls.Select<string>("Servers (read-only)")
    .AddItems(servers)
    .Default("web-01")
    .ViewOnly()
    .Run();

---

Dynamic description

ChangeDescription

ISelectControl<T> ChangeDescription(Func<T, string> value)

Recomputes the description from the currently focused item as the user navigates.

PromptPlus.Controls.Select<string>("City")
    .AddItems(cities)
    .ChangeDescription(city => $"You are on: {city}")
    .Run();

---

ChangeDescriptionAsync

ISelectControl<T> ChangeDescriptionAsync(Func<T, Task<string>> value)

Asynchronous version of ChangeDescription.

---

History

EnableHistory

ISelectControl<T> EnableHistory(string filename, Action<IHistoryOptions>? options = null)

Persists confirmed selections to filename and can pre-select the last one (via Default or UseDefaultHistory). The IHistoryOptions builder is identical to the one documented for Input → EnableHistory (MinPrefixLength, MaxItems, ExpirationTime, FilterType, PageSize).

PromptPlus.Controls.Select<string>("City")
    .AddItems(cities)
    .EnableHistory("city-history", opt => opt.MaxItems(8).FilterType(FilterMode.StartsWith))
    .UseDefaultHistory()
    .Run();

---

Appearance & behavior

Styles

ISelectControl<T> Styles(SelectStyles styleType, Style style)

Recolors one visual region of this control. See the region list and examples on the Styles page.

using PromptPlusLibrary;
using ConsolePlusLibrary;   // Color, Style live here
PromptPlus.Controls.Select<string>("City").AddItems(cities)
    .Styles(SelectStyles.Selected, new Style(Color.Blue, Color.Default))
    .Run();

---

Options

ISelectControl<T> Options(Action<IControlOptions> options)

Overrides global behaviors for this one control (prompt/description text, abort key, tooltip, hide-after-finish, extra-info affixes). See Global Behaviors → Per-Control Override.

---

Running the control

Run

ResultPrompt<T> Run(CancellationToken token = default)

Renders the list and blocks until the user confirms (Enter) or aborts (Esc). Returns ResultPrompt<T>.

var result = PromptPlus.Controls.Select<string>("City").AddItems(cities).Run();

---

See also

• Operations — how these methods behave at runtime
• Styles — the SelectStyles regions
• Index — overview and method map

This site is open source. Improve this page.