Spectre.Console Documentation

The BarChart widget visualizes numeric data as horizontal bars with labels and optional values.

When to Use

Use BarChart when you need to compare discrete values across categories. Common scenarios:

Ranking or comparison: Show sales by region, votes by candidate, or scores by team
Progress tracking: Display completion percentages or metrics against targets
Survey results: Visualize response counts or ratings

For part-to-whole relationships (showing how pieces make up a total), use BreakdownChart instead.

Basic Usage

Add items with a label, value, and optional color.

csharp

var chart = new BarChart()
    .AddItem("Apple", 12, Color.Green)
    .AddItem("Orange", 8, Color.Orange1)
    .AddItem("Banana", 5, Color.Yellow);
  
AnsiConsole.Write(chart);

Adding a Title

Use Label() to add context above the chart. Supports markup for styling.

csharp

var chart = new BarChart()
    .Label("[bold underline]Fruit Sales[/]")
    .AddItem("Apple", 12, Color.Green)
    .AddItem("Orange", 8, Color.Orange1)
    .AddItem("Banana", 5, Color.Yellow);
  
AnsiConsole.Write(chart);

Align the label with LeftAlignLabel(), CenterLabel(), or RightAlignLabel().

csharp

AnsiConsole.MarkupLine("[yellow]Left aligned:[/]");
var left = new BarChart()
    .Label("Sales Data")
    .LeftAlignLabel()
    .AddItem("Q1", 100, Color.Blue)
    .AddItem("Q2", 150, Color.Green);
AnsiConsole.Write(left);
  
AnsiConsole.WriteLine();
AnsiConsole.MarkupLine("[yellow]Center aligned (default):[/]");
var center = new BarChart()
    .Label("Sales Data")
    .CenterLabel()
    .AddItem("Q1", 100, Color.Blue)
    .AddItem("Q2", 150, Color.Green);
AnsiConsole.Write(center);
  
AnsiConsole.WriteLine();
AnsiConsole.MarkupLine("[yellow]Right aligned:[/]");
var right = new BarChart()
    .Label("Sales Data")
    .RightAlignLabel()
    .AddItem("Q1", 100, Color.Blue)
    .AddItem("Q2", 150, Color.Green);
AnsiConsole.Write(right);

Customizing Values

Formatting

When displaying currency, percentages, or units, use UseValueFormatter().

csharp

var chart = new BarChart()
    .Label("[bold]Revenue by Region[/]")
    .UseValueFormatter((value, culture) => value.ToString("C0", culture))
    .AddItem("North", 125000, Color.Blue)
    .AddItem("South", 98000, Color.Green)
    .AddItem("East", 145000, Color.Yellow)
    .AddItem("West", 112000, Color.Red);
  
AnsiConsole.Write(chart);

Hiding Values

Use HideValues() when the visual comparison matters more than exact numbers.

csharp

AnsiConsole.MarkupLine("[yellow]With values (default):[/]");
var withValues = new BarChart()
    .AddItem("Downloads", 1250, Color.Blue)
    .AddItem("Uploads", 340, Color.Green);
AnsiConsole.Write(withValues);
  
AnsiConsole.WriteLine();
AnsiConsole.MarkupLine("[yellow]Without values:[/]");
var noValues = new BarChart()
    .HideValues()
    .AddItem("Downloads", 1250, Color.Blue)
    .AddItem("Uploads", 340, Color.Green);
AnsiConsole.Write(noValues);

Scaling

By default, bars scale relative to the largest value. Use WithMaxValue() to set a fixed scale—useful when comparing against a target or showing progress toward a goal.

csharp

var chart = new BarChart()
    .Label("[bold]Progress to Goal (100)[/]")
    .WithMaxValue(100)
    .AddItem("Team A", 85, Color.Green)
    .AddItem("Team B", 62, Color.Yellow)
    .AddItem("Team C", 45, Color.Red);
  
AnsiConsole.Write(chart);

Working with Data Collections

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

csharp

var data = new[]
{
    new BarChartItem("January", 45, Color.Blue),
    new BarChartItem("February", 62, Color.Blue),
    new BarChartItem("March", 58, Color.Blue),
    new BarChartItem("April", 71, Color.Green),
};
  
var chart = new BarChart()
    .Label("[bold]Monthly Performance[/]")
    .AddItems(data);
  
AnsiConsole.Write(chart);

API Reference

A renderable (horizontal) bar chart.

Constructors

public BarChart()

Initializes a new instance of the BarChart class.

Properties

Culture : CultureInfo

Gets or sets the culture that's used to format values.

Data : List<IBarChartItem>

Gets the bar chart data.

Label : string

Gets or sets the bar chart label.

LabelAlignment : Justify?

Gets or sets the bar chart label alignment.

MaxValue : double?

Gets or sets the fixed max value for a bar chart.

ShowValues : bool

Gets or sets a value indicating whether or not values should be shown next to each bar.

ValueFormatter : Func<double, CultureInfo, string>

Gets or sets the function used to format the values of the bar chart.

Width : int?

Gets or sets the width of the bar chart.

BarChart Widget