ProgressBar

Quick start

Use ProgressBar when the UI should expose completion, load state, validation-adjacent status, or background activity without exposing direct manipulation. The same control can render as a classic determinate fill, a vertical meter, or an indeterminate activity strip.

Minimal determinate bar

<ProgressBar Width="260"
             Minimum="0"
             Maximum="100"
             Value="64" />

Vertical meter

<ProgressBar Width="10"
             Height="140"
             Orientation="Vertical"
             Minimum="0"
             Maximum="1"
             Value="0.3" />

Indeterminate activity bar

<ProgressBar Width="220"
             Height="10"
             IsIndeterminate="True" />

What the range means

ProgressBar inherits Minimum, Maximum, and Value from RangeBase. Those properties are always kept in a legal state, and the effective value is what drives the filled geometry, the template-part layout, and the read-only automation surface.

<ProgressBar Width="240"
             Minimum="0"
             Maximum="1"
             Value="0.42" />

That bar renders at roughly forty-two percent of the available track length. If Value is later assigned to 2, the visible fill still resolves to the effective maximum.

How the control renders

ProgressBar has two rendering modes. Determinate mode maps the effective range value into a visible fill segment. Indeterminate mode ignores percentage display and advances an animated segment each frame across the resolved track area.

<StackPanel>
  <TextBlock Text="Upload progress" Margin="0,0,0,6" />
  <ProgressBar Width="260"
               Minimum="0"
               Maximum="100"
               Value="72" />

  <TextBlock Text="Waiting for workers" Margin="0,14,0,6" />
  <ProgressBar Width="260"
               Height="10"
               IsIndeterminate="True" />
</StackPanel>

This is the common production pattern: show a determinate bar whenever the system can provide a percentage, and switch to indeterminate only when the work is active but not yet measurable.

Template structure and visual states

ProgressBar is a templated control. The shipped theme uses named parts plus template-root visual states. When those parts exist, the runtime sizes and repositions them directly during arrange and per-frame indeterminate updates. When they do not exist, the control falls back to its direct renderer instead of throwing.

• PART_Track supplies the geometry used for both percentage fill and indeterminate travel.
• PART_Indicator is resized and repositioned directly by the control.
• Template visual states resolve against the applied template root, so setters can target named parts in the template tree.
• Template teardown clears active visual-state-owned values when the control leaves a state or swaps templates.

Template example

<ControlTemplate TargetType="{x:Type ProgressBar}">
  <Border x:Name="RootChrome">
    <VisualStateManager.VisualStateGroups>
      <VisualStateGroup x:Name="CommonStates">
        <VisualState x:Name="Determinate" />
        <VisualState x:Name="Indeterminate">
          <VisualState.Setters>
            <Setter TargetName="PART_GlowRect" Property="Opacity" Value="0.8" />
          </VisualState.Setters>
        </VisualState>
      </VisualStateGroup>
      <VisualStateGroup x:Name="ValidationStates">
        <VisualState x:Name="Valid" />
        <VisualState x:Name="InvalidFocused" />
        <VisualState x:Name="InvalidUnfocused" />
      </VisualStateGroup>
    </VisualStateManager.VisualStateGroups>

    <Grid x:Name="PART_Track">
      <Border x:Name="PART_Indicator" />
      <Border x:Name="PART_GlowRect" Opacity="0" />
    </Grid>
  </Border>
</ControlTemplate>

Layout and sizing

ProgressBar participates in normal layout, but its fallback renderer maintains a few minimum expectations so a standalone bar remains legible even when the parent does not constrain it tightly.

<StackPanel Orientation="Horizontal">
  <ProgressBar Width="240"
               Height="18"
               Minimum="0"
               Maximum="100"
               Value="35" />

  <ProgressBar Width="18"
               Height="180"
               Margin="16,0,0,0"
               Orientation="Vertical"
               Minimum="0"
               Maximum="100"
               Value="65" />
</StackPanel>

Property and event reference

Patterns and examples

Task completion bar

<StackPanel>
  <TextBlock Text="Exporting assets" Margin="0,0,0,6" />
  <ProgressBar Width="300"
               Minimum="0"
               Maximum="500"
               Value="315" />
</StackPanel>

Compact vertical meters

<StackPanel Orientation="Horizontal">
  <ProgressBar Width="10" Height="120" Orientation="Vertical" Value="15" Maximum="100" />
  <ProgressBar Width="10" Height="120" Orientation="Vertical" Margin="8,0,0,0" Value="55" Maximum="100" />
  <ProgressBar Width="10" Height="120" Orientation="Vertical" Margin="8,0,0,0" Value="88" Maximum="100" />
</StackPanel>

Indeterminate worker status

<Border Padding="12"
        Background="#101923"
        BorderBrush="#334A61"
        BorderThickness="1">
  <StackPanel>
    <TextBlock Text="Polling remote workers" Margin="0,0,0,8" />
    <ProgressBar Height="10"
                 IsIndeterminate="True"
                 Foreground="#F0B45A"
                 Background="#223344" />
  </StackPanel>
</Border>

Validation-aware template usage

<ProgressBar Width="260"
             Height="12"
             Minimum="0"
             Maximum="100"
             Value="40"
             Foreground="{StaticResource OrangePrimaryBrush}"
             Background="{StaticResource DarkElevatedBrush}" />

When the control enters an invalid state, the default template switches its validation visual state without changing the range value itself.

Code-driven setup

var progressBar = new ProgressBar
{
    Width = 280f,
    Height = 18f,
    Minimum = 0f,
    Maximum = 1f,
    Value = 0f,
    Background = new Color(24, 24, 24),
    Foreground = new Color(72, 146, 210),
    BorderBrush = new Color(98, 98, 98),
    BorderThickness = 1f
};

progressBar.ValueChanged += (_, _) =>
{
    statusText.Text = $"{progressBar.Value:P0}";
};

progressBar.Value = 0.58f;

Switching between measurable and unknown work

progressBar.IsIndeterminate = true;

// Later, once the backend reports real progress:
progressBar.IsIndeterminate = false;
progressBar.Minimum = 0f;
progressBar.Maximum = totalSteps;
progressBar.Value = completedSteps;

Notes and pitfalls