Spectre.Console

SelectionPrompt

Let users select a single option from a list with keyboard navigation

The SelectionPrompt creates interactive menus where users navigate with arrow keys to select one option from a list.

When to Use

Use SelectionPrompt when you need to present a clear set of mutually exclusive options. Common scenarios:

  • Menu navigation: Main menus, configuration choices, action selection
  • Categorical selection: Countries, languages, categories with defined options
  • Mode switching: Environment selection (Dev/Stage/Prod), output formats, themes

For multiple selections, use MultiSelectionPrompt instead. For free-form text input, use TextPrompt instead.

Caution

Selection prompts are not thread safe. Using them together with other interactive components such as progress displays, status displays, or other prompts is not supported.

Basic Usage

The simplest selection prompt needs a title and choices.

csharp 
var fruit = AnsiConsole.Prompt(
    new SelectionPrompt<string>()
        .Title("What's your favorite fruit?")
        .AddChoices("Apple", "Banana", "Orange", "Mango", "Strawberry"));
  
AnsiConsole.MarkupLine($"You selected: [green]{fruit}[/]");

Adding a Title

Use markup to style the title and draw attention to key information.

csharp 
var language = AnsiConsole.Prompt(
    new SelectionPrompt<string>()
        .Title("Which [green]programming language[/] do you prefer?")
        .AddChoices("C#", "Python", "JavaScript", "Java", "Go"));
  
AnsiConsole.MarkupLine($"Great choice! [blue]{language}[/] is awesome.");

Populating Choices

Multiple Ways to Add Choices

You can add choices using params arrays, IEnumerable collections, or individual AddChoice calls.

csharp 
// Using params array
var prompt1 = new SelectionPrompt<string>()
    .Title("Select a color (params)")
    .AddChoices("Red", "Green", "Blue");
  
// Using IEnumerable
var colors = new[] { "Red", "Green", "Blue", "Yellow", "Purple" };
var prompt2 = new SelectionPrompt<string>()
    .Title("Select a color (IEnumerable)")
    .AddChoices(colors);
  
var selectedColor = AnsiConsole.Prompt(prompt2);
AnsiConsole.MarkupLine($"You selected: [bold]{selectedColor}[/]");

Hierarchical Choices

Use AddChoiceGroup() to organize choices into categories with parent-child relationships.

csharp 
var country = AnsiConsole.Prompt(
    new SelectionPrompt<string>()
        .Title("Select your [green]destination[/]")
        .PageSize(15)
        .AddChoiceGroup("Europe", new[]
        {
            "France", "Germany", "Italy", "Spain", "United Kingdom"
        })
        .AddChoiceGroup("Asia", new[]
        {
            "China", "Japan", "South Korea", "Thailand", "Singapore"
        })
        .AddChoiceGroup("Americas", new[]
        {
            "United States", "Canada", "Mexico", "Brazil", "Argentina"
        }));
  
AnsiConsole.MarkupLine($"Bon voyage to [yellow]{country}[/]!");

Pagination

Use PageSize() to control how many items display at once, and customize the hint text shown when more choices exist.

csharp 
var cities = new[]
{
    "New York", "Los Angeles", "Chicago", "Houston", "Phoenix",
    "Philadelphia", "San Antonio", "San Diego", "Dallas", "San Jose",
    "Austin", "Jacksonville", "Fort Worth", "Columbus", "Charlotte"
};
  
var city = AnsiConsole.Prompt(
    new SelectionPrompt<string>()
        .Title("Select a city")
        .PageSize(5)
        .MoreChoicesText("[grey](Use arrow keys to see more cities)[/]")
        .AddChoices(cities));
  
AnsiConsole.MarkupLine($"You selected: [blue]{city}[/]");

Wrap-Around

Enable WrapAround() for circular navigation - pressing up at the top jumps to the bottom, and vice versa.

csharp 
var season = AnsiConsole.Prompt(
    new SelectionPrompt<string>()
        .Title("Select your favorite [green]season[/]")
        .WrapAround()
        .AddChoices("Spring", "Summer", "Fall", "Winter"));
  
AnsiConsole.MarkupLine($"You selected: [yellow]{season}[/]");

Use EnableSearch() to let users type and filter the list instantly - essential for long lists.

csharp 
var countries = new[]
{
    "Argentina", "Australia", "Brazil", "Canada", "China", "Egypt",
    "France", "Germany", "India", "Italy", "Japan", "Mexico",
    "Netherlands", "Russia", "South Africa", "South Korea", "Spain",
    "Sweden", "Switzerland", "Thailand", "Turkey", "United Kingdom",
    "United States", "Vietnam"
};
  
var country = AnsiConsole.Prompt(
    new SelectionPrompt<string>()
        .Title("Select a [green]country[/]")
        .PageSize(10)
        .EnableSearch()
        .SearchPlaceholderText("Type to search countries...")
        .AddChoices(countries));
  
AnsiConsole.MarkupLine($"You selected: [blue]{country}[/]");

Search Highlighting

Customize how matched characters are highlighted during search with SearchHighlightStyle().

csharp 
var technologies = new[]
{
    "ASP.NET Core", "Angular", "React", "Vue.js", "Node.js",
    "Docker", "Kubernetes", "PostgreSQL", "MongoDB", "Redis",
    "GraphQL", "gRPC", "RabbitMQ", "Kafka", "Elasticsearch"
};
  
var prompt = new SelectionPrompt<string>()
    .Title("Select a [green]technology[/]")
    .PageSize(8)
    .EnableSearch()
    .SearchPlaceholderText("Type to filter...")
    .AddChoices(technologies);
  
prompt.SearchHighlightStyle = new Style(Color.Yellow, decoration: Decoration.Underline);
  
var tech = AnsiConsole.Prompt(prompt);
AnsiConsole.MarkupLine($"You selected: [blue]{tech}[/]");

Styling

Highlight Style

Use HighlightStyle() to customize the appearance of the currently selected item.

csharp 
var option = AnsiConsole.Prompt(
    new SelectionPrompt<string>()
        .Title("Select an option")
        .HighlightStyle(new Style(Color.Green, Color.Black, Decoration.Bold))
        .AddChoices("Option 1", "Option 2", "Option 3", "Option 4"));
  
AnsiConsole.MarkupLine($"You selected: [green]{option}[/]");

Disabled Item Style

Use DisabledStyle() to style non-selectable items like group headers.

csharp 
var prompt = new SelectionPrompt<string>()
    .Title("Select a [green]sport[/]")
    .AddChoiceGroup("Team Sports", new[]
    {
        "Basketball", "Soccer", "Baseball", "Volleyball"
    })
    .AddChoiceGroup("Individual Sports", new[]
    {
        "Tennis", "Swimming", "Running", "Cycling"
    });
  
prompt.DisabledStyle = new Style(Color.Grey, decoration: Decoration.Italic);
  
var sport = AnsiConsole.Prompt(prompt);
AnsiConsole.MarkupLine($"You chose: [yellow]{sport}[/]");

Selection Modes

Leaf Mode

Use SelectionMode.Leaf to only allow selecting leaf nodes - parent group headers become non-selectable.

csharp 
var file = AnsiConsole.Prompt(
    new SelectionPrompt<string>()
        .Title("Select a [green]file[/]")
        .PageSize(15)
        .Mode(SelectionMode.Leaf)
        .AddChoiceGroup("Documents", new[]
        {
            "Resume.pdf", "CoverLetter.docx", "References.txt"
        })
        .AddChoiceGroup("Images", new[]
        {
            "Photo1.jpg", "Photo2.png", "Logo.svg"
        })
        .AddChoiceGroup("Code", new[]
        {
            "Program.cs", "Helpers.cs", "README.md"
        }));
  
AnsiConsole.MarkupLine($"Opening: [blue]{file}[/]");

Independent Mode

Use SelectionMode.Independent to allow selecting both parent groups and their children.

csharp 
var category = AnsiConsole.Prompt(
    new SelectionPrompt<string>()
        .Title("Select a [green]category or item[/]")
        .PageSize(15)
        .Mode(SelectionMode.Independent)
        .AddChoiceGroup("Electronics", new[]
        {
            "Laptops", "Smartphones", "Tablets"
        })
        .AddChoiceGroup("Clothing", new[]
        {
            "Shirts", "Pants", "Shoes"
        })
        .AddChoiceGroup("Books", new[]
        {
            "Fiction", "Non-Fiction", "Science"
        }));
  
AnsiConsole.MarkupLine($"You selected: [yellow]{category}[/]");

Working with Complex Objects

Use UseConverter() to display custom formatted text for complex objects while returning the actual object.

csharp 
var books = new[]
{
    new Book { Title = "The Great Gatsby", Author = "F. Scott Fitzgerald", Year = 1925 },
    new Book { Title = "To Kill a Mockingbird", Author = "Harper Lee", Year = 1960 },
    new Book { Title = "1984", Author = "George Orwell", Year = 1949 },
    new Book { Title = "Pride and Prejudice", Author = "Jane Austen", Year = 1813 },
    new Book { Title = "The Catcher in the Rye", Author = "J.D. Salinger", Year = 1951 }
};
  
var selectedBook = AnsiConsole.Prompt(
    new SelectionPrompt<Book>()
        .Title("Select a [green]book[/]")
        .PageSize(10)
        .UseConverter(book => $"{book.Title} by {book.Author} ({book.Year})")
        .AddChoices(books));
  
AnsiConsole.MarkupLine($"You selected: [yellow]{selectedBook.Title}[/]");

Complete Example

This comprehensive example combines search, pagination, wrap-around, custom styling, and complex objects for a realistic project selection menu.

csharp 
var projects = new[]
{
    new Project { Name = "E-Commerce Platform", Status = "Active", Priority = "High" },
    new Project { Name = "Mobile App Redesign", Status = "Active", Priority = "Medium" },
    new Project { Name = "API Gateway", Status = "Planning", Priority = "High" },
    new Project { Name = "Customer Portal", Status = "Active", Priority = "Low" },
    new Project { Name = "Analytics Dashboard", Status = "Completed", Priority = "Medium" },
    new Project { Name = "Payment Integration", Status = "Active", Priority = "High" },
    new Project { Name = "User Authentication", Status = "Completed", Priority = "High" },
    new Project { Name = "Email Service", Status = "Planning", Priority = "Low" }
};
  
var prompt = new SelectionPrompt<Project>()
    .Title("Select a [green]project[/] to view details")
    .PageSize(6)
    .MoreChoicesText("[grey](Move up and down to see more projects)[/]")
    .EnableSearch()
    .SearchPlaceholderText("Type to search projects...")
    .WrapAround()
    .HighlightStyle(new Style(Color.Cyan1, decoration: Decoration.Bold))
    .UseConverter(p => $"[bold]{p.Name}[/] - {p.Status} [{GetPriorityColor(p.Priority)}]{p.Priority}[/]")
    .AddChoices(projects);
  
prompt.SearchHighlightStyle = new Style(Color.Yellow, decoration: Decoration.Underline);
  
var selected = AnsiConsole.Prompt(prompt);
  
AnsiConsole.WriteLine();
AnsiConsole.Write(new Panel($"[bold]{selected.Name}[/]\nStatus: {selected.Status}\nPriority: {selected.Priority}")
    .Header("Project Details")
    .BorderColor(Color.Cyan1));

See Also

API Reference

Represents a single list prompt.

Constructors

public SelectionPrompt`1(IEqualityComparer<T> comparer = null)

Initializes a new instance of the SelectionPrompt class.

Parameters:

comparer (IEqualityComparer<T>)
The IEqualityComparer implementation to use when comparing items, or null to use the default IEqualityComparer for the type of the item.

Properties

CancelResult : Func<T>

Gets or sets a Func that will be triggered if Cancel is triggered by the 'ESC' key.

Converter : Func<T, string>

Gets or sets the converter to get the display string for a choice. By default the corresponding TypeConverter is used.

DefaultValue : T

Gets or sets the choice to show as selected when the prompt is first displayed. By default the first choice is selected.

Mode : SelectionMode

Gets or sets the selection mode. Defaults to Leaf.

MoreChoicesText : string

Gets or sets the text that will be displayed if there are more choices to show.

PageSize : int

Gets or sets the page size. Defaults to 10.

SearchEnabled : bool

Gets or sets a value indicating whether or not search is enabled.

SearchPlaceholderText : string

Gets or sets the text that will be displayed when no search text has been entered.

Title : string

Gets or sets the title.

WrapAround : bool

Gets or sets a value indicating whether the selection should wrap around when reaching the edge. Defaults to false.

Methods

public ISelectionItem<T> AddChoice(T item)

Adds a choice.

Parameters:

item (T)
The item to add.

Returns:

A ISelectionItem so that multiple calls can be chained.

public T Show(IAnsiConsole console)

Shows the prompt.

Parameters:

console (IAnsiConsole)
The console.

Returns:

The prompt input result.

public Task<T> ShowAsync(IAnsiConsole console, CancellationToken cancellationToken)

Shows the prompt asynchronously.

Parameters:

console (IAnsiConsole)
The console.
cancellationToken (CancellationToken)
The token to monitor for cancellation requests.

Returns:

The prompt input result.

Extension Methods

SelectionPrompt<T> AddCancelResult<T>(this SelectionPrompt<T> obj, T cancelResult)

Sets a Func that will be triggered if the prompt is cancelled with 'ESC'.

Returns:

The same instance so that multiple calls can be chained.

SelectionPrompt<T> AddCancelResult<T>(this SelectionPrompt<T> obj, Func<T> cancelResultFunc)

Sets the value that will be returned if the prompt is cancelled with 'ESC'.

Returns:

The same instance so that multiple calls can be chained.

SelectionPrompt<T> AddChoiceGroup<T>(this SelectionPrompt<T> obj, T group, T[] choices)

Adds multiple grouped choices.

Returns:

The same instance so that multiple calls can be chained.

SelectionPrompt<T> AddChoiceGroup<T>(this SelectionPrompt<T> obj, T group, IEnumerable<T> choices)

Adds multiple grouped choices.

Returns:

The same instance so that multiple calls can be chained.

SelectionPrompt<T> AddChoices<T>(this SelectionPrompt<T> obj, T[] choices)

Adds multiple choices.

Returns:

The same instance so that multiple calls can be chained.

SelectionPrompt<T> AddChoices<T>(this SelectionPrompt<T> obj, IEnumerable<T> choices)

Adds multiple choices.

Returns:

The same instance so that multiple calls can be chained.

SelectionPrompt<T> DisableSearch<T>(this SelectionPrompt<T> obj)

Disables search for the prompt.

Returns:

The same instance so that multiple calls can be chained.

SelectionPrompt<T> EnableSearch<T>(this SelectionPrompt<T> obj)

Enables search for the prompt.

Returns:

The same instance so that multiple calls can be chained.

SelectionPrompt<T> Mode<T>(this SelectionPrompt<T> obj, SelectionMode mode)

Sets the selection mode.

Returns:

The same instance so that multiple calls can be chained.

SelectionPrompt<T> PageSize<T>(this SelectionPrompt<T> obj, int pageSize)

Sets how many choices that are displayed to the user.

Returns:

The same instance so that multiple calls can be chained.

SelectionPrompt<T> SearchPlaceholderText<T>(this SelectionPrompt<T> obj, string text)

Sets the text that will be displayed when no search text has been entered.

Returns:

The same instance so that multiple calls can be chained.

SelectionPrompt<T> Title<T>(this SelectionPrompt<T> obj, string title)

Sets the title.

Returns:

The same instance so that multiple calls can be chained.

SelectionPrompt<T> WrapAround<T>(this SelectionPrompt<T> obj, bool shouldWrap)

Sets whether the selection should wrap around when reaching its edges.

Returns:

The same instance so that multiple calls can be chained.