Skip to main content
The Bar Chart widget renders horizontal or vertical bars with automatic scaling, labels, and value display.

​
Basic Usage

import { ui } from "@rezi-ui/core";

ui.barChart({
  data: [
    { label: "Product A", value: 45 },
    { label: "Product B", value: 32 },
    { label: "Product C", value: 58 },
  ],
});

​
Props

​
key
string
Reconciliation key.
​
data
BarChartItem[]
required
Data items to display. Each item has:
  • label: string - Item label
  • value: number - Item value
  • variant?: BadgeVariant - Optional color variant
​
orientation
horizontal | vertical
default:"horizontal"
Chart orientation.
​
showValues
boolean
default:"true"
Show numeric values on bars.
​
showLabels
boolean
default:"true"
Show item labels.
​
maxBarLength
number
Maximum bar length in cells. Auto-scales if omitted.
​
highRes
boolean
default:"false"
Enable sub-cell rendering for smoother bars.
​
blitter
GraphicsBlitter
Rendering mode for highRes mode. One of "braille", "sextant", "quadrant", "halfblock".
​
style
TextStyle
Optional style override for chart.

​
Data Format

type BarChartItem = {
  label: string;
  value: number;
  variant?: "default" | "success" | "warning" | "error" | "info";
};

​
Basic Data

ui.barChart({
  data: [
    { label: "Mon", value: 12 },
    { label: "Tue", value: 19 },
    { label: "Wed", value: 15 },
    { label: "Thu", value: 25 },
    { label: "Fri", value: 22 },
  ],
});

​
Colored Bars

ui.barChart({
  data: [
    { label: "Passed", value: 85, variant: "success" },
    { label: "Failed", value: 12, variant: "error" },
    { label: "Skipped", value: 3, variant: "warning" },
  ],
});

​
Orientation

​
Horizontal (Default)

Bars extend to the right: 
ui.barChart({
  orientation: "horizontal",
  data: [
    { label: "Alpha", value: 40 },
    { label: "Beta", value: 65 },
    { label: "Gamma", value: 30 },
  ],
});
Output: 
Alpha  ████████████████████ 40
Beta   █████████████████████████████████ 65
Gamma  ███████████████ 30

​
Vertical

Bars extend upward: 
ui.barChart({
  orientation: "vertical",
  data: [
    { label: "Q1", value: 20 },
    { label: "Q2", value: 35 },
    { label: "Q3", value: 28 },
    { label: "Q4", value: 42 },
  ],
});

​
Display Options

​
Hide Values

ui.barChart({
  data: items,
  showValues: false,
});

​
Hide Labels

ui.barChart({
  data: items,
  showLabels: false,
});

​
Fixed Bar Length

ui.barChart({
  data: items,
  maxBarLength: 40, // All bars scale to 40 cells max
});

​
High-Resolution Mode

Enable sub-cell rendering for smoother bars: 
ui.barChart({
  data: items,
  highRes: true,
  blitter: "sextant", // 2x3 sub-cell blocks
});
Best blitters for bar charts:
  • "sextant" - Best balance of resolution and visibility
  • "halfblock" - Good for horizontal bars
  • "quadrant" - Good for vertical bars

​
Examples

​
Test Results

function testResultsChart(results: {
  passed: number;
  failed: number;
  skipped: number;
}): VNode {
  return ui.column({ gap: 1 }, [
    ui.text("Test Results", { variant: "heading" }),
    ui.barChart({
      data: [
        { label: "Passed", value: results.passed, variant: "success" },
        { label: "Failed", value: results.failed, variant: "error" },
        { label: "Skipped", value: results.skipped, variant: "warning" },
      ],
      maxBarLength: 50,
    }),
  ]);
}

​
Resource Usage

function resourceChart(resources: Array<{
  name: string;
  used: number;
  total: number;
}>): VNode {
  const data = resources.map((r) => ({
    label: r.name,
    value: (r.used / r.total) * 100,
    variant: r.used / r.total > 0.9 ? "error" : "success",
  }));
  
  return ui.column({ gap: 1 }, [
    ui.text("Resource Usage", { variant: "heading" }),
    ui.barChart({
      data,
      showValues: true,
    }),
  ]);
}

​
Sales Comparison

function salesComparison(sales: Array<{
  product: string;
  amount: number;
}>): VNode {
  const sorted = [...sales].sort((a, b) => b.amount - a.amount);
  
  return ui.column({ gap: 1 }, [
    ui.text("Top Products", { variant: "heading" }),
    ui.barChart({
      orientation: "horizontal",
      data: sorted.slice(0, 10).map((s) => ({
        label: s.product,
        value: s.amount,
      })),
      maxBarLength: 60,
      highRes: true,
      blitter: "sextant",
    }),
  ]);
}

​
Vertical Timeline

function activityTimeline(hours: Array<{
  hour: string;
  events: number;
}>): VNode {
  return ui.column({ gap: 1 }, [
    ui.text("Hourly Activity", { variant: "heading" }),
    ui.barChart({
      orientation: "vertical",
      data: hours.map((h) => ({
        label: h.hour,
        value: h.events,
      })),
      showValues: true,
    }),
  ]);
}

​
Threshold Coloring

function metricChart(
  metrics: Array<{ name: string; value: number }>,
  thresholds: { warning: number; error: number }
): VNode {
  const data = metrics.map((m) => {
    let variant: BarChartItem["variant"] = "success";
    if (m.value >= thresholds.error) {
      variant = "error";
    } else if (m.value >= thresholds.warning) {
      variant = "warning";
    }
    
    return {
      label: m.name,
      value: m.value,
      variant,
    };
  });
  
  return ui.barChart({ data });
}

​
Compact Dashboard

function compactMetrics(metrics: Record<string, number>): VNode {
  return ui.column({ gap: 1 }, [
    ui.text("System Metrics", { variant: "heading" }),
    ui.barChart({
      data: Object.entries(metrics).map(([label, value]) => ({
        label,
        value,
      })),
      showLabels: true,
      showValues: true,
      maxBarLength: 30,
    }),
  ]);
}

​
Stacked View Simulation

function categoryBreakdown(
  categories: Array<{ name: string; values: number[] }>
): VNode {
  return ui.column({ gap: 2 }, [
    ui.text("Category Breakdown", { variant: "heading" }),
    ...categories.map((cat) =>
      ui.column({ gap: 0, key: cat.name }, [
        ui.text(cat.name, { style: { bold: true } }),
        ui.barChart({
          data: cat.values.map((v, i) => ({
            label: `Item ${i + 1}`,
            value: v,
          })),
          showLabels: false,
          maxBarLength: 40,
        }),
      ])
    ),
  ]);
}

​
Styling

​
Custom Colors

ui.barChart({
  data: items,
  style: {
    fg: "#3b82f6",
    bold: true,
  },
});

​
Per-Item Variants

Use the variant field for semantic colors: 
const data: BarChartItem[] = [
  { label: "Low", value: 20, variant: "success" },
  { label: "Medium", value: 50, variant: "warning" },
  { label: "High", value: 80, variant: "error" },
];

ui.barChart({ data });

​
Performance

  • Standard mode: Instant for any reasonable dataset
  • High-res mode: Best for < 100 items
  • Vertical orientation: Requires more vertical space

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us