LumaxForge
ZH EN

Bar Chart (Bar)

easy-chart-lit · Manual

Back to Product Chapters

Bar Chart (Bar)

This chapter explains bar charts in EasyChart: the data interpretation rules (SeriesData.x/value), how grouping/stacking really behaves, and commonly used style fields.

1. Use cases

  • Category comparisons (compare values of A/B/C)
  • Grouped comparison (multiple Bar series side-by-side under the same category)
  • Stacked totals (stack bars within the same category)

2. Minimum viable setup (checklist)

  1. ChartProfile.coordinateSystem = Cartesian2D
  2. Axes
    • X: usually AxisType.Category (fill labels)
    • Y: usually AxisType.Value (recommended to start from 0)
  3. Series
    • Add 1 Serie
    • Serie.type = Bar
    • Serie.seriesData has at least 1 point

3. Inspector fields

  • Axis Settings

    • cartesian.xAxisId / cartesian.yAxisId
    • axes[] (AxisConfig for X/Y)

  • Series

    • series[i].type = Bar
    • series[i].settings: actual type is BarSettings
      • barWidth
      • stacked / stackGroup
      • barGap / categoryGap
      • cornerRadius / cornerSegments
      • textureFill (color/texture)
      • border / background
      • hover (enables picking/highlight)

4. SeriesData field interpretation (runtime behavior)

Bar charts primarily use:

  • Category / horizontal position: SeriesData.x

    • Runtime rounds x with RoundToInt, so treat it as a category index.

  • Bar height: SeriesData.value

  • SeriesData.y / SeriesData.z are not used for rendering in Bar charts (do not treat y as height).

5. Most common template: Category X + Value Y

5.1 X axis (Category)

  • AxisType = Category
  • labels = ["A","B","C",...]
  • Recommended: labelPlacement = CellCenter (easier to center-align bars)

5.2 Data pattern

  • x = category index (0/1/2…)
  • value = bar height

6. Grouped bars (multiple series side-by-side): the actual rule

Key points:

  • multiple Serie, all type=Bar
  • all series share the same X categories (same labels)
  • each series uses the same x index to land in the same category

Spacing fields:

  • BarSettings.barGap: gap between bar groups within a category
  • BarSettings.categoryGap: extra gap between categories (affects edge padding)

7. Stacked bars (stacked): the actual rule

Stacking happens between Bar series with the same stackGroup:

  • BarSettings.stacked = true
  • BarSettings.stackGroup = "Group1"

Runtime stacking notes:

  • for the same x (category index), it accumulates positive and negative values separately (positive/negative stacks are separate)
  • the top of each stacked segment = current accumulated base + value

8. Common pitfalls and troubleshooting

  • Bars appear between labels / not aligned

    • Check X axis labelPlacement (recommend CellCenter)
    • Ensure x is an integer index (runtime rounds)

  • Bars do not start from 0

    • Check whether Y axis (Value Axis) has autoRangeMin disabled and minValue=0 locked

  • Stacking result is wrong

    • Check that all series that should stack use the same stackGroup
    • Remember: positive and negative values stack separately

9. Further reading

  • Axes/range, Series and data: 00_02-WorkflowAndLibrary.md
  • Common recipes: 04_08-CommonRecipes.md
  • FAQ: 04_09-FAQ.md