Spectre.Console Documentation

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.

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.

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.

// 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.

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.

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.

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

Search

Enabling Search

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

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().

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.

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.

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.

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.

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.

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.

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

API Reference

Represents a single list prompt.

Constructors

SelectionPrompt`1()

Initializes a new instance of the class.

Properties

Converter : Func<T, string>

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

DisabledStyle : Style

Gets or sets the style of a disabled choice.

HighlightStyle : Style

Gets or sets the highlight style of the selected choice.

Mode : SelectionMode

Gets or sets the selection mode. Defaults to .

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.

SearchHighlightStyle : Style

Gets or sets the style of highlighted search matches.

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

ISelectionItem<T> AddChoice(T item)

Parameters:

item (T)

T Show(IAnsiConsole console)

Parameters:

console (IAnsiConsole)

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

Parameters:

console (IAnsiConsole)

cancellationToken (CancellationToken)

SelectionPrompt

When to Use

Basic Usage

Adding a Title

Populating Choices

Multiple Ways to Add Choices

Hierarchical Choices

Navigation

Wrap-Around

Search

Enabling Search

Search Highlighting

Styling

Highlight Style

Disabled Item Style

Selection Modes

Leaf Mode

Independent Mode

Working with Complex Objects

Complete Example

See Also

API Reference

Constructors

Properties

Methods