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.

Basic Usage

The simplest selection prompt needs a title and choices.

public static void BasicSelectionExample()
{
    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.

public static void SelectionWithTitleExample()
{
    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.

public static void AddChoicesVariationsExample()
{
    // 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.

public static void HierarchicalChoicesExample()
{
    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.

public static void PageSizeExample()
{
    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.

public static void WrapAroundExample()
{
    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.

public static void SearchEnabledExample()
{
    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().

public static void SearchHighlightStyleExample()
{
    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.

public static void HighlightStyleExample()
{
    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.

public static void DisabledStyleExample()
{
    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.

public static void SelectionModeLeafExample()
{
    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.

public static void SelectionModeIndependentExample()
{
    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.

public static void CustomConverterExample()
{
    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.

public static void CompleteExampleWithAllFeatures()
{
    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)