Spectre.Console

BarChart Widget

Display data as horizontal bars with labels, values, and colors

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

Screenshot

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.

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

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

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

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

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

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

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

BarChart()

Initializes a new instance of the 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 : Nullable<Justify>

Gets or sets the bar chart label alignment.

MaxValue : Nullable<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 : Nullable<int>

Gets or sets the width of the bar chart.

Extension Methods

BarChart AddItem(string label, double value, Nullable<Color> color)

Adds an item to the bar chart.

Parameters:

label (string)
The item label.
value (double)
The item value.
color (Nullable<Color>)
The item color.

Returns:

The same instance so that multiple calls can be chained.

BarChart AddItem(T item)

Parameters:

item (T)
BarChart AddItems(IEnumerable<T> items)

Parameters:

items (IEnumerable<T>)
BarChart AddItems(IEnumerable<T> items, Func<T, BarChartItem> converter)

Parameters:

items (IEnumerable<T>)
converter (Func<T, BarChartItem>)
BarChart CenterLabel()

Centers the label.

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 .

BarChart HideValues()

Hides values next to each bar in the bar chart.

Returns:

The same instance so that multiple calls can be chained.

BarChart Label(string label)

Sets the label of the bar chart.

Parameters:

label (string)
The bar chart label.

Returns:

The same instance so that multiple calls can be chained.

BarChart LeftAlignLabel()

Aligns the label to the left.

Returns:

The same instance so that multiple calls can be chained.

BarChart RightAlignLabel()

Aligns the label to the right.

Returns:

The same instance so that multiple calls can be chained.

BarChart ShowValues()

Shows values next to each bar in the bar chart.

Returns:

The same instance so that multiple calls can be chained.

BarChart ShowValues(bool show)

Sets whether or not values should be shown next to each bar.

Parameters:

show (bool)
Whether or not values should be shown next to each bar.

Returns:

The same instance so that multiple calls can be chained.

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

Sets the value formatter for the bar chart using culture info.

Parameters:

func (Func<double, CultureInfo, string>)
The value formatter function with culture info.

Returns:

The same instance so that multiple calls can be chained.

BarChart UseValueFormatter(Func<double, string> func)

Sets the value formatter for the bar chart.

Parameters:

func (Func<double, string>)
The value formatter to use.

Returns:

The same instance so that multiple calls can be chained.

BarChart Width(Nullable<int> width)

Sets the width of the bar chart.

Parameters:

width (Nullable<int>)
The bar chart width.

Returns:

The same instance so that multiple calls can be chained.

BarChart WithMaxValue(double maxValue)

Sets the max fixed value for the chart.

Parameters:

maxValue (double)
Max value for the chart.

Returns:

The same instance so that multiple calls can be chained.