Spectre.Console

Status Display

Show animated status indicators with spinners for ongoing operations

The Status display renders an animated spinner with a status message for long-running operations.

When to Use

Use Status when you need to indicate ongoing work without tracking specific progress. Common scenarios:

  • Indeterminate operations: Show activity when duration or completion percentage is unknown
  • Connection attempts: Display feedback while connecting to services or loading resources
  • Background processing: Indicate that work is happening behind the scenes

For operations with measurable progress (file downloads, batch processing), use Progress instead.

Basic Usage

Create a status display by calling AnsiConsole.Status().Start() with a message and a callback containing your work.

public static void BasicStatusExample()
{
    AnsiConsole.Status()
        .Start("Processing data...", ctx =>
        {
            // Simulate work
            Thread.Sleep(3000);
  
            AnsiConsole.MarkupLine("[green]Processing complete![/]");
        });
}

Spinners

Choosing a Spinner

Select a spinner animation that matches your application's style or the type of operation being performed.

public static void StatusSpinnerExample()
{
    AnsiConsole.Status()
        .Spinner(Spinner.Known.Star)
        .Start("Loading resources...", ctx =>
        {
            Thread.Sleep(2000);
            AnsiConsole.MarkupLine("[green]Resources loaded![/]");
        });
}

Note

See the Spinner Reference for a gallery of all available spinner animations.

Styling the Spinner

Apply colors and styles to the spinner to convey meaning or match your application's theme.

public static void StatusSpinnerStyleExample()
{
    AnsiConsole.Status()
        .Spinner(Spinner.Known.Dots)
        .SpinnerStyle(Style.Parse("bold yellow"))
        .Start("Connecting to server...", ctx =>
        {
            Thread.Sleep(2500);
            AnsiConsole.MarkupLine("[green]Connected successfully![/]");
        });
}

Async Operations

Use StartAsync() when working with asynchronous code to avoid blocking the UI thread.

public static async Task StatusAsyncExample()
{
    await AnsiConsole.Status()
        .StartAsync("Downloading files...", async ctx =>
        {
            // Simulate async work
            await Task.Delay(3000);
  
            AnsiConsole.MarkupLine("[green]Download complete![/]");
        });
}

Returning Values

Status operations can return values from the callback, allowing you to retrieve results after completion.

public static void StatusWithReturnValueExample()
{
    var result = AnsiConsole.Status()
        .Start("Calculating results...", ctx =>
        {
            // Simulate calculation
            Thread.Sleep(2000);
  
            return 42;
        });
  
    AnsiConsole.MarkupLine($"[green]Result: {result}[/]");
}

Dynamic Updates

Changing Status Text

Update the status message as your operation progresses through different stages.

public static void StatusDynamicUpdateExample()
{
    AnsiConsole.Status()
        .Start("Starting process...", ctx =>
        {
            ctx.Status("Loading configuration...");
            Thread.Sleep(1000);
  
            ctx.Status("Connecting to database...");
            Thread.Sleep(1500);
  
            ctx.Status("Fetching data...");
            Thread.Sleep(1000);
  
            ctx.Status("Processing records...");
            Thread.Sleep(1500);
  
            AnsiConsole.MarkupLine("[green]All tasks completed![/]");
        });
}

Changing the Spinner

Switch spinner animations at runtime to indicate different types of activity.

public static void StatusSpinnerChangeExample()
{
    AnsiConsole.Status()
        .Start("Initializing...", ctx =>
        {
            ctx.Status("Starting services...");
            ctx.Spinner(Spinner.Known.Dots);
            Thread.Sleep(1500);
  
            ctx.Status("Loading modules...");
            ctx.Spinner(Spinner.Known.Line);
            Thread.Sleep(1500);
  
            ctx.Status("Running diagnostics...");
            ctx.Spinner(Spinner.Known.BouncingBar);
            Thread.Sleep(1500);
  
            ctx.Status("Finalizing...");
            ctx.Spinner(Spinner.Known.Star);
            Thread.Sleep(1000);
  
            AnsiConsole.MarkupLine("[green]System ready![/]");
        });
}

Manual Refresh

Disable automatic refresh when you need precise control over when the status display updates.

public static void StatusManualRefreshExample()
{
    AnsiConsole.Status()
        .AutoRefresh(false)
        .Start("Processing batch...", ctx =>
        {
            for (int i = 1; i <= 5; i++)
            {
                ctx.Status($"Processing item {i} of 5...");
                ctx.Refresh();
  
                Thread.Sleep(800);
  
                AnsiConsole.MarkupLine($"[grey]Item {i} processed[/]");
            }
  
            AnsiConsole.MarkupLine("[green]Batch complete![/]");
        });
}

Markup Support

Use Spectre.Console's markup syntax in status text to add colors, styles, and emphasis.

public static void StatusWithMarkupExample()
{
    AnsiConsole.Status()
        .Spinner(Spinner.Known.Dots)
        .Start("[yellow]Initializing[/]...", ctx =>
        {
            Thread.Sleep(1000);
  
            ctx.Status("[blue]Connecting to [bold]API server[/][/]...");
            Thread.Sleep(1500);
  
            ctx.Status("[cyan]Authenticating user[/]...");
            Thread.Sleep(1000);
  
            ctx.Status("[green]Loading [italic]user preferences[/][/]...");
            Thread.Sleep(1500);
  
            AnsiConsole.MarkupLine("[bold green]Startup complete![/]");
        });
}

API Reference

Represents a status display.

Constructors

Status(IAnsiConsole console)

Initializes a new instance of the class.

Parameters:

console (IAnsiConsole)
The console.

Properties

AutoRefresh : bool

Gets or sets a value indicating whether or not status should auto refresh. Defaults to true.

Spinner : Spinner

Gets or sets the spinner.

SpinnerStyle : Style

Gets or sets the spinner style.

Methods

Start(string status, Action<StatusContext> action)

Starts a new status display.

Parameters:

status (string)
The status to display.
action (Action<StatusContext>)
The action to execute.
T Start(string status, Func<StatusContext, T> func)

Parameters:

status (string)
func (Func<StatusContext, T>)
Task StartAsync(string status, Func<StatusContext, Task> action)

Starts a new status display.

Parameters:

status (string)
The status to display.
action (Func<StatusContext, Task>)
The action to execute.

Returns:

A representing the asynchronous operation.

Task<T> StartAsync(string status, Func<StatusContext, Task<T>> func)

Parameters:

status (string)
func (Func<StatusContext, Task<T>>)

Extension Methods

Status AutoRefresh(bool enabled)

Sets whether or not auto refresh is enabled. If disabled, you will manually have to refresh the progress.

Parameters:

enabled (bool)
Whether or not auto refresh is enabled.

Returns:

The same instance so that multiple calls can be chained.

Status Spinner(Spinner spinner)

Sets the spinner.

Parameters:

spinner (Spinner)
The spinner.

Returns:

The same instance so that multiple calls can be chained.

Status SpinnerStyle(Style style)

Sets the spinner style.

Parameters:

style (Style)
The spinner style.

Returns:

The same instance so that multiple calls can be chained.