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.

public static void BasicBreakdownChartExample()
{
    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.

public static void BreakdownChartPercentageExample()
{
    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.

public static void BreakdownChartFormattingExample()
{
    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.

public static void BreakdownChartTagsExample()
{
    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.

public static void BreakdownChartCompactExample()
{
    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.

public static void BreakdownChartWidthExample()
{
    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.

public static void BreakdownChartAddItemsExample()
{
    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

BreakdownChart()

Initializes a new instance of the 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 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.

ValueColor : Color

Gets or sets the Color in which the values will be shown.

ValueFormatter : Func<double, CultureInfo, string>

Gets or sets the tag value formatter.

Width : Nullable<int>

Gets or sets the width of the breakdown chart.

Extension Methods

BreakdownChart AddItem(string label, double value, Color color)

Adds an item to the breakdown chart.

Parameters:

label (string)

The item label.

value (double)

The item value.

color (Color)

The item color.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart AddItem(T item)

Parameters:

item (T)

BreakdownChart AddItems(IEnumerable<T> items)

Parameters:

items (IEnumerable<T>)

BreakdownChart AddItems(IEnumerable<T> items, Func<T, IBreakdownChartItem> converter)

Parameters:

items (IEnumerable<T>)

converter (Func<T, IBreakdownChartItem>)

BreakdownChart Compact()

Chart and tags is rendered in compact mode.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart Compact(bool compact)

Sets whether or not the chart and tags should be rendered in compact mode.

Parameters:

compact (bool)

Whether or not the chart and tags should be rendered in compact mode.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart FullSize()

Chart and tags is rendered in full size mode.

Returns:

The same instance so that multiple calls can be chained.

IEnumerable<Segment> GetSegments(IAnsiConsole console)

Gets the segments for a renderable using the specified console.

Parameters:

console (IAnsiConsole)

The console.

Returns:

An enumerable containing segments representing the specified .

BreakdownChart HideTags()

Tags will be not be shown.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart HideTagValues()

Tag values will be not be shown.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart ShowPercentage()

Tags will be shown.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart ShowTags()

Tags will be shown.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart ShowTags(bool show)

Sets whether or not tags will be shown.

Parameters:

show (bool)

Whether or not tags will be shown.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart ShowTagValues()

Tag values will be shown.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart ShowTagValues(bool show)

Sets whether or not tag values will be shown.

Parameters:

show (bool)

Whether or not tag values will be shown.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart UseValueFormatter(Func<double, CultureInfo, string> func)

Tags will be shown.

Parameters:

func (Func<double, CultureInfo, string>)

The value formatter to use.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart UseValueFormatter(Func<double, string> func)

Tags will be shown.

Parameters:

func (Func<double, string>)

The value formatter to use.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart Width(Nullable<int> width)

Sets the width of the breakdown chart.

Parameters:

width (Nullable<int>)

The breakdown chart width.

Returns:

The same instance so that multiple calls can be chained.

BreakdownChart WithValueColor(Color color)

Sets the .

Parameters:

color (Color)

The to set.

Returns:

The same instance so that multiple calls can be chained.