Spectre.Console Documentation

The Progress display renders animated progress bars for tracking task completion in real-time.

When to Use

Use Progress when you need to track completion status for long-running operations. Common scenarios:

Multi-step processes: Show progress across multiple sequential or concurrent tasks
File operations: Display download, upload, or processing progress
Build pipelines: Track compilation, testing, and deployment steps
Data processing: Monitor record processing, imports, or transformations

For simple status messages without progress tracking, use Status instead. For real-time data updates, consider Live Display.

Basic Usage

Create a progress context and add tasks to track their completion.

public static void BasicProgressExample()
{
    AnsiConsole.Progress()
        .Start(ctx =>
        {
            var task = ctx.AddTask("Processing files");
  
            while (!ctx.IsFinished)
            {
                task.Increment(1);
                Thread.Sleep(50);
            }
        });
}

Managing Tasks

Multiple Tasks

Track several concurrent operations with individual progress bars.

public static void ProgressMultipleTasksExample()
{
    AnsiConsole.Progress()
        .Start(ctx =>
        {
            var task1 = ctx.AddTask("Downloading images");
            var task2 = ctx.AddTask("Processing documents");
            var task3 = ctx.AddTask("Compiling code");
  
            while (!ctx.IsFinished)
            {
                task1.Increment(1.5);
                task2.Increment(0.8);
                task3.Increment(1.2);
                Thread.Sleep(50);
            }
        });
}

Increment vs Value Assignment

Use Increment() for relative progress updates or set Value directly for absolute positioning.

public static void ProgressIncrementExample()
{
    AnsiConsole.Progress()
        .Start(ctx =>
        {
            var task = ctx.AddTask("Processing records", maxValue: 100);
  
            // Increment by a specific amount
            for (int i = 0; i < 50; i++)
            {
                task.Increment(2);
                Thread.Sleep(20);
            }
  
            // Or set the value directly
            task.Value = 75;
            Thread.Sleep(500);
  
            task.Value = 100;
        });
}

Indeterminate Progress

Use IsIndeterminate() when the total duration or size is unknown, showing an animated progress bar without percentage.

public static void ProgressIndeterminateExample()
{
    AnsiConsole.Progress()
        .Start(ctx =>
        {
            var task = ctx.AddTask("Connecting to server")
                .IsIndeterminate();
  
            Thread.Sleep(2000);
  
            // Once we know the total, switch to determinate
            task.IsIndeterminate(false);
            task.MaxValue = 100;
  
            while (!ctx.IsFinished)
            {
                task.Increment(2);
                Thread.Sleep(30);
            }
        });
}

Adding Tasks Dynamically

Add new tasks during execution based on discovered work or changing requirements.

public static void ProgressDynamicTasksExample()
{
    AnsiConsole.Progress()
        .Start(ctx =>
        {
            var scan = ctx.AddTask("Scanning directory");
  
            while (!scan.IsFinished)
            {
                scan.Increment(2);
                Thread.Sleep(50);
            }
  
            // After scanning, add new tasks for found items
            var process1 = ctx.AddTask("Processing report.pdf");
            var process2 = ctx.AddTask("Processing data.xlsx");
  
            while (!ctx.IsFinished)
            {
                process1.Increment(1.5);
                process2.Increment(1.2);
                Thread.Sleep(50);
            }
        });
}

Updating Descriptions

Change task descriptions during execution to provide detailed status updates.

public static void ProgressTaskDescriptionUpdateExample()
{
    AnsiConsole.Progress()
        .Start(ctx =>
        {
            var task = ctx.AddTask("Processing", maxValue: 100);
  
            for (int i = 1; i <= 100; i++)
            {
                task.Description = $"Processing file {i} of 100";
                task.Increment(1);
                Thread.Sleep(30);
            }
        });
}

Display Columns

Custom Column Configuration

Configure which information columns appear in the progress display using Columns().

public static void ProgressCustomColumnsExample()
{
    AnsiConsole.Progress()
        .Columns(
            new TaskDescriptionColumn(),
            new ProgressBarColumn(),
            new PercentageColumn(),
            new RemainingTimeColumn())
        .Start(ctx =>
        {
            var task = ctx.AddTask("Processing data");
  
            while (!ctx.IsFinished)
            {
                task.Increment(0.5);
                Thread.Sleep(50);
            }
        });
}

Available Columns

Column	Purpose
`TaskDescriptionColumn`	Shows the task description text
`ProgressBarColumn`	Displays the animated progress bar
`PercentageColumn`	Shows completion percentage
`RemainingTimeColumn`	Estimates time until completion
`ElapsedTimeColumn`	Shows time since task started
`SpinnerColumn`	Adds an animated spinner indicator
`DownloadedColumn`	Shows downloaded bytes (formatted)
`TransferSpeedColumn`	Shows transfer rate (bytes/sec)

Spinner Animation

Add visual feedback with a spinning animation indicator.

public static void ProgressWithSpinnerExample()
{
    AnsiConsole.Progress()
        .Columns(
            new TaskDescriptionColumn(),
            new ProgressBarColumn(),
            new PercentageColumn(),
            new SpinnerColumn())
        .Start(ctx =>
        {
            var task = ctx.AddTask("Analyzing files");
  
            while (!ctx.IsFinished)
            {
                task.Increment(0.8);
                Thread.Sleep(60);
            }
        });
}

Timing Information

Display elapsed time and remaining time estimates for operations.

public static void ProgressTimingColumnsExample()
{
    AnsiConsole.Progress()
        .Columns(
            new TaskDescriptionColumn(),
            new ProgressBarColumn(),
            new PercentageColumn(),
            new ElapsedTimeColumn(),
            new RemainingTimeColumn())
        .Start(ctx =>
        {
            var task = ctx.AddTask("Converting video", maxValue: 100);
  
            while (!ctx.IsFinished)
            {
                task.Increment(1);
                Thread.Sleep(100);
            }
        });
}

Download Progress

Use specialized columns for file download scenarios with size and speed information.

public static void ProgressDownloadExample()
{
    AnsiConsole.Progress()
        .Columns(
            new TaskDescriptionColumn(),
            new ProgressBarColumn(),
            new DownloadedColumn(),
            new TransferSpeedColumn(),
            new RemainingTimeColumn())
        .Start(ctx =>
        {
            var task = ctx.AddTask("game-installer.exe", maxValue: 524288000); // 500 MB in bytes
  
            while (!ctx.IsFinished)
            {
                task.Increment(2621440); // 2.5 MB per tick
                Thread.Sleep(50);
            }
        });
}

Styling

Customize progress bar appearance with colors to match your application theme or convey meaning.

public static void ProgressBarStylingExample()
{
    AnsiConsole.Progress()
        .Columns(
            new TaskDescriptionColumn(),
            new ProgressBarColumn()
            {
                CompletedStyle = new Style(Color.Green),
                FinishedStyle = new Style(Color.Lime),
                RemainingStyle = new Style(Color.Grey)
            },
            new PercentageColumn())
        .Start(ctx =>
        {
            var task = ctx.AddTask("Building project");
  
            while (!ctx.IsFinished)
            {
                task.Increment(1);
                Thread.Sleep(40);
            }
        });
}

Refresh Behavior

Auto Clear

Automatically remove the progress display after all tasks complete using AutoClear(true).

public static void ProgressAutoClearExample()
{
    AnsiConsole.Progress()
        .AutoClear(true)
        .Start(ctx =>
        {
            var task = ctx.AddTask("Temporary operation");
  
            while (!ctx.IsFinished)
            {
                task.Increment(2);
                Thread.Sleep(50);
            }
        });
  
    AnsiConsole.MarkupLine("[green]Operation complete![/]");
}

Hide Completed Tasks

Remove completed tasks from view while keeping active ones visible using HideCompleted(true).

public static void ProgressHideCompletedExample()
{
    AnsiConsole.Progress()
        .HideCompleted(true)
        .Start(ctx =>
        {
            var task1 = ctx.AddTask("Step 1", maxValue: 50);
            var task2 = ctx.AddTask("Step 2", maxValue: 50);
            var task3 = ctx.AddTask("Step 3", maxValue: 50);
  
            // Complete task 1
            while (!task1.IsFinished)
            {
                task1.Increment(2);
                Thread.Sleep(50);
            }
  
            // Complete task 2
            while (!task2.IsFinished)
            {
                task2.Increment(2);
                Thread.Sleep(50);
            }
  
            // Complete task 3
            while (!task3.IsFinished)
            {
                task3.Increment(2);
                Thread.Sleep(50);
            }
        });
}

Async Operations

Use StartAsync() for async/await scenarios with Task-based operations.

public static async Task ProgressAsyncExample()
{
    await AnsiConsole.Progress()
        .StartAsync(async ctx =>
        {
            var task1 = ctx.AddTask("Async operation 1");
            var task2 = ctx.AddTask("Async operation 2");
  
            var operations = new[]
            {
                Task.Run(async () =>
                {
                    while (!task1.IsFinished)
                    {
                        task1.Increment(1);
                        await Task.Delay(50);
                    }
                }),
                Task.Run(async () =>
                {
                    while (!task2.IsFinished)
                    {
                        task2.Increment(0.8);
                        await Task.Delay(60);
                    }
                })
            };
  
            await Task.WhenAll(operations);
        });
}

Returning Values

Progress operations can return values for use after completion.

public static void ProgressReturnValueExample()
{
    var result = AnsiConsole.Progress()
        .Start(ctx =>
        {
            var task = ctx.AddTask("Processing items", maxValue: 100);
            int processedCount = 0;
  
            while (!ctx.IsFinished)
            {
                task.Increment(1);
                processedCount++;
                Thread.Sleep(20);
            }
  
            return processedCount;
        });
  
    AnsiConsole.MarkupLine($"[green]Processed {result} items[/]");
}

API Reference

Represents a task list.

Constructors

Progress(IAnsiConsole console)

Initializes a new instance of the class.

Parameters:

console (IAnsiConsole)

The console to render to.

Properties

AutoClear : bool

Gets or sets a value indicating whether or not the task list should be cleared once it completes. Defaults to false.

AutoRefresh : bool

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

HideCompleted : bool

Gets or sets a value indicating whether or not the task list should only include tasks not completed Defaults to false.

RefreshRate : TimeSpan

Gets or sets the refresh rate if AutoRefresh is enabled. Defaults to 10 times/second.

RenderHook : Func<IRenderable, IReadOnlyList<ProgressTask>, IRenderable>

Gets or sets a optional custom render function.

Methods

Start(Action<ProgressContext> action)

Starts the progress task list.

Parameters:

action (Action<ProgressContext>)

The action to execute.

T Start(Func<ProgressContext, T> func)

Parameters:

func (Func<ProgressContext, T>)

Task StartAsync(Func<ProgressContext, Task> action)

Starts the progress task list.

Parameters:

action (Func<ProgressContext, Task>)

The action to execute.

Returns:

A representing the asynchronous operation.

Task<T> StartAsync(Func<ProgressContext, Task<T>> action)

Parameters:

action (Func<ProgressContext, Task<T>>)

Extension Methods

Progress AutoClear(bool enabled)

Sets whether or not auto clear is enabled. If enabled, the task tabled will be removed once all tasks have completed.

Parameters:

enabled (bool)

Whether or not auto clear is enabled.

Returns:

The same instance so that multiple calls can be chained.

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

Progress Columns(ProgressColumn[] columns)

Sets the columns to be used for an instance.

Parameters:

columns (ProgressColumn[])

The columns to use.

Returns:

The same instance so that multiple calls can be chained.

Progress HideCompleted(bool enabled)

Sets whether or not hide completed is enabled. If enabled, the task tabled will be removed once it is completed.

Parameters:

enabled (bool)

Whether or not hide completed is enabled.

Returns:

The same instance so that multiple calls can be chained.

Progress UseRenderHook(Func<IRenderable, IReadOnlyList<ProgressTask>, IRenderable> renderHook)

Sets an optional hook to intercept rendering.

Parameters:

renderHook (Func<IRenderable, IReadOnlyList<ProgressTask>, IRenderable>)

The custom render function.

Returns:

The same instance so that multiple calls can be chained.