Spectre.Console Documentation - BreakdownChart Widget

The BreakdownChart widget displays proportional data as a single horizontal bar divided into colored segments.

When to Use

Use BreakdownChart when you need to show how parts make up a whole. Common scenarios:

Resource allocation: Disk space used vs. available, memory distribution
Composition: Market share breakdown, budget allocation by category
Status overview: Tasks completed vs. in progress vs. pending

For comparing independent values (where items don't sum to a meaningful total), use BarChart instead.

Basic Usage

Add items with a label, value, and color. The bar automatically scales segments proportionally.

csharp

var chart = new BreakdownChart()
    .AddItem("C#", 78, Color.Green)
    .AddItem("Python", 45, Color.Blue)
    .AddItem("JavaScript", 32, Color.Yellow)
    .AddItem("Rust", 15, Color.Red);
  
AnsiConsole.Write(chart);

Displaying Values

As Percentages

Use ShowPercentage() when relative proportions matter more than absolute numbers.

csharp

var chart = new BreakdownChart()
    .ShowPercentage()
    .AddItem("Completed", 73, Color.Green)
    .AddItem("In Progress", 18, Color.Yellow)
    .AddItem("Not Started", 9, Color.Grey);
  
AnsiConsole.Write(chart);

With Custom Formatting

Use UseValueFormatter() to add units or custom formatting.

csharp

var chart = new BreakdownChart()
    .UseValueFormatter((value, culture) => $"{value:N0} GB")
    .AddItem("Documents", 45, Color.Blue)
    .AddItem("Photos", 120, Color.Green)
    .AddItem("Videos", 280, Color.Purple);
  
AnsiConsole.Write(chart);

Controlling the Legend

The legend (tags) below the chart shows labels and values. Control visibility when space is limited or when the chart speaks for itself.

csharp

AnsiConsole.MarkupLine("[yellow]With tags and values (default):[/]");
var withTags = new BreakdownChart()
    .AddItem("Downloads", 1250, Color.Blue)
    .AddItem("Uploads", 340, Color.Green);
AnsiConsole.Write(withTags);
  
AnsiConsole.WriteLine();
AnsiConsole.MarkupLine("[yellow]With tags, without values:[/]");
var tagsOnly = new BreakdownChart()
    .HideTagValues()
    .AddItem("Downloads", 1250, Color.Blue)
    .AddItem("Uploads", 340, Color.Green);
AnsiConsole.Write(tagsOnly);
  
AnsiConsole.WriteLine();
AnsiConsole.MarkupLine("[yellow]Without tags:[/]");
var noTags = new BreakdownChart()
    .HideTags()
    .AddItem("Downloads", 1250, Color.Blue)
    .AddItem("Uploads", 340, Color.Green);
AnsiConsole.Write(noTags);

Layout

Compact vs Full-Size

Use Compact() (default) for tight layouts. Use FullSize() to add spacing between the bar and legend for better readability.

csharp

AnsiConsole.MarkupLine("[yellow]Compact mode (default):[/]");
var compact = new BreakdownChart()
    .Compact()
    .AddItem("Used", 75, Color.Red)
    .AddItem("Free", 25, Color.Green);
AnsiConsole.Write(compact);
  
AnsiConsole.WriteLine();
AnsiConsole.MarkupLine("[yellow]Full-size mode:[/]");
var fullSize = new BreakdownChart()
    .FullSize()
    .AddItem("Used", 75, Color.Red)
    .AddItem("Free", 25, Color.Green);
AnsiConsole.Write(fullSize);

Fixed Width

By default the chart expands to fill available width. Use Width() to constrain it.

csharp

var chart = new BreakdownChart()
    .Width(40)
    .AddItem("Category A", 60, Color.Blue)
    .AddItem("Category B", 40, Color.Green);
  
AnsiConsole.Write(chart);

Working with Data Collections

Use AddItems() to add multiple items from a collection of BreakdownChartItem objects.

csharp

var data = new[]
{
    new BreakdownChartItem("Q1", 125, Color.Blue),
    new BreakdownChartItem("Q2", 180, Color.Green),
    new BreakdownChartItem("Q3", 165, Color.Yellow),
    new BreakdownChartItem("Q4", 210, Color.Red),
};
  
var chart = new BreakdownChart()
    .AddItems(data);
  
AnsiConsole.Write(chart);

API Reference

A renderable breakdown chart.

Constructors

public BreakdownChart()

Initializes a new instance of the BreakdownChart class.

Properties

Compact : bool

Gets or sets a value indicating whether or not the chart and tags should be rendered in compact mode.

Culture : CultureInfo

Gets or sets the CultureInfo to use when rendering values.

Data : List<IBreakdownChartItem>

Gets the breakdown chart data.

Expand : bool

Gets or sets a value indicating whether or not the object should expand to the available space. If false, the object's width will be auto calculated.

ShowTags : bool

Gets or sets a value indicating whether or not to show tags.

ShowTagValues : bool

Gets or sets a value indicating whether or not to show tag values.

ValueFormatter : Func<double, CultureInfo, string>

Gets or sets the tag value formatter.

Width : int?

Gets or sets the width of the breakdown chart.