Progress

Display progress bars for operations with known or unknown completion amounts.

Basic Usage

Create a simple progress bar using the fluent API. By default, progress uses a 0-100 range:

csharp

using Hex1b;

await using var terminal = Hex1bTerminal.CreateBuilder()
    .WithHex1bApp((app, options) => ctx => ctx.VStack(v => [
        v.Text("Download Progress"),
        v.Progress(75),
        v.Text(""),
        v.Text("Upload Progress"),
        v.Progress(30)
    ]))
    .Build();

await terminal.RunAsync();

dotnet run

Determinate Progress

Use determinate progress when you know how much of the operation is complete. The progress bar fills proportionally based on the current value:

csharp

Custom Ranges

Progress supports any numeric range, not just 0-100. This is useful for showing bytes downloaded, items processed, or any other measurable quantity:

csharp

The range can even include negative values (e.g., for temperature scales).

Indeterminate Progress

Use indeterminate progress when you don't know how long an operation will take. An animated segment bounces back and forth automatically:

csharp

using Hex1b;

await using var terminal = Hex1bTerminal.CreateBuilder()
    .WithHex1bApp((app, options) => ctx => ctx.VStack(v => [
        v.Text("Loading..."),
        v.ProgressIndeterminate()  // Self-animating!
    ]))
    .Build();

await terminal.RunAsync();

dotnet run

The progress bar is self-animating—no external timer or manual position updates are required. The animation is time-based internally, so it runs at a consistent speed regardless of screen refresh rate.

csharp

Layout Behavior

By default, the progress bar fills all available horizontal space. Use layout extensions to constrain its width:

// Full width (default)
v.Progress(50)

// Fixed width
v.Progress(50).FixedWidth(30)

// Proportional width in HStack
h.Progress(50).Fill()

Theming

Customize the appearance of progress bars using the theme system:

csharp

Available theme elements:

Element	Default	Description
FilledCharacter	█	Character for completed portion
EmptyCharacter	░	Character for remaining portion
IndeterminateCharacter	█	Character for animated segment
FilledForegroundColor	Green	Color for completed portion
EmptyForegroundColor	DarkGray	Color for remaining portion
IndeterminateForegroundColor	Cyan	Color for animated segment

Related Widgets

• Spinner - For indicating activity without progress amount
• Text - For displaying status messages alongside progress
• Layout & Stacks - For arranging progress bars with labels