Bar charts visualize categorical data using rectangular bars where height represents the data value. Kuva’s BarPlot supports three modes: simple (one bar per category), grouped (multiple side-by-side bars), and stacked (bars stacked vertically).
When to Use
- Comparing quantities across categories
- Showing counts or frequencies
- Displaying multiple series per category (grouped mode)
- Showing part-to-whole relationships over categories (stacked mode)
- Time series with discrete categories (quarters, years)
Basic Example
use kuva::plot::BarPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;
let plot = BarPlot::new()
.with_bars(vec![
("Apples", 42.0),
("Bananas", 58.0),
("Cherries", 31.0),
])
.with_color("steelblue");
let plots = vec![Plot::Bar(plot)];
let layout = Layout::auto_from_plots(&plots)
.with_title("Fruit Counts")
.with_y_label("Count");
let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
std::fs::write("bar.svg", svg).unwrap();
Three Modes
Simple Mode
One bar per category with uniform color:
let plot = BarPlot::new()
.with_bars(vec![
("Q1", 42.0),
("Q2", 58.0),
("Q3", 51.0),
("Q4", 67.0),
])
.with_color("steelblue");
Grouped Mode
Multiple bars side-by-side per category:
let plot = BarPlot::new()
.with_group("Q1", vec![(18.0, "steelblue"), (12.0, "crimson"), (9.0, "seagreen")])
.with_group("Q2", vec![(22.0, "steelblue"), (17.0, "crimson"), (14.0, "seagreen")])
.with_group("Q3", vec![(19.0, "steelblue"), (21.0, "crimson"), (11.0, "seagreen")])
.with_legend(vec!["Product A", "Product B", "Product C"]);
Stacked Mode
Bars stacked vertically within each category:
let plot = BarPlot::new()
.with_group("Q1", vec![(18.0, "steelblue"), (12.0, "crimson"), (9.0, "seagreen")])
.with_group("Q2", vec![(22.0, "steelblue"), (17.0, "crimson"), (14.0, "seagreen")])
.with_group("Q3", vec![(19.0, "steelblue"), (21.0, "crimson"), (11.0, "seagreen")])
.with_legend(vec!["Product A", "Product B", "Product C"])
.with_stacked();
Key Methods
Simple Mode Methods
Add a single bar:.with_bar("Category A", 42.0)
.with_bar("Category B", 58.0)
Add multiple bars at once:.with_bars(vec![
("A", 42.0),
("B", 58.0),
("C", 31.0),
])
Set uniform color for all bars (in simple mode):Call this after adding bars with .with_bar() or .with_bars(). Grouped/Stacked Mode Methods
Add a group of bars for one category:.with_group("Q1", vec![
(10.0, "steelblue"), // value, color
(7.0, "crimson"),
(5.0, "seagreen"),
])
(value, color) pair represents one series. Call this once per x-axis category. Set legend labels for each series:.with_legend(vec!["Series A", "Series B", "Series C"])
Enable stacked mode (vertical stacking instead of side-by-side): Sizing
Set bar width as a fraction of the category slot (default 0.8):.with_width(0.6) // Narrower bars
.with_width(1.0) // Bars touch each other
0.0 and 1.0. Examples
Simple Bar Chart
let plot = BarPlot::new()
.with_bars(vec![
("Apples", 42.0),
("Bananas", 58.0),
("Cherries", 31.0),
("Dates", 47.0),
("Elderberry", 25.0),
])
.with_color("steelblue");
Grouped Bar Chart
let plot = BarPlot::new()
.with_group("Q1", vec![(18.0, "steelblue"), (12.0, "crimson"), (9.0, "seagreen")])
.with_group("Q2", vec![(22.0, "steelblue"), (17.0, "crimson"), (14.0, "seagreen")])
.with_group("Q3", vec![(19.0, "steelblue"), (21.0, "crimson"), (11.0, "seagreen")])
.with_group("Q4", vec![(25.0, "steelblue"), (15.0, "crimson"), (18.0, "seagreen")])
.with_legend(vec!["Product A", "Product B", "Product C"]);
Stacked Bar Chart
let plot = BarPlot::new()
.with_group("Q1", vec![(18.0, "steelblue"), (12.0, "crimson"), (9.0, "seagreen")])
.with_group("Q2", vec![(22.0, "steelblue"), (17.0, "crimson"), (14.0, "seagreen")])
.with_group("Q3", vec![(19.0, "steelblue"), (21.0, "crimson"), (11.0, "seagreen")])
.with_group("Q4", vec![(25.0, "steelblue"), (15.0, "crimson"), (18.0, "seagreen")])
.with_legend(vec!["Product A", "Product B", "Product C"])
.with_stacked();
Custom Bar Width
let plot = BarPlot::new()
.with_bars(vec![("A", 10.0), ("B", 15.0), ("C", 12.0)])
.with_color("steelblue")
.with_width(0.5); // Narrower bars with more whitespace
Tips
Choosing mode: Use simple for single-series data, grouped to compare series side-by-side, and stacked to show composition and totals.
Color consistency: In grouped/stacked mode, use the same colors across all groups so each series has a consistent color throughout.
Many categories: If you have many categories, consider horizontal bars (not yet supported) or rotate to a different plot type like a dot plot.
In grouped/stacked mode, every group must have the same number of bars. The legend labels must match this count.
Negative values are supported and will extend downward from the x-axis.
Source Location
Implementation: src/plot/bar.rs
Examples: examples/bar.rs