Histogram — Chart Controls

Data Shape

A histogram accepts either raw numeric values (the control buckets them automatically) or pre-bucketed data with explicit bin ranges:

// Option A: Raw values — control auto-buckets using binCount
// [{ "value": 142 }, { "value": 87 }, { "value": 203 }, ...]
// OR flat array:
// [142, 87, 203, 91, ...]

// Option B: Pre-bucketed data
// [
//   { "label": "0–25ms",    "value": 312 },
//   { "label": "25–50ms",   "value": 841 },
//   { "label": "50–100ms",  "value": 428 },
//   { "label": "100–200ms", "value": 93  }
// ]

Settings Reference

Setting	Type	Default	Description
`binCount`	number	10	Number of bins when auto-bucketing raw values
`dataMode`	`raw` \| `bucketed`	`raw`	Whether data is raw values (auto-bin) or pre-bucketed (use as-is)
`showFrequencyLine`	boolean	false	Overlay a frequency polygon (line connecting bin midpoints)
`showMeanLine`	boolean	false	Draw a vertical reference line at the mean
`showMedianLine`	boolean	false	Draw a vertical reference line at the median
`barGap`	string (CSS %)	`"0%"`	Gap between bars — default 0% gives the traditional histogram look
`normalize`	boolean	false	Show relative frequency (0–1) instead of absolute count on the y-axis
`chartConfig.xAxis`	object	—	X axis: label, format
`chartConfig.yAxis`	object	—	Y axis: label (defaults to "Frequency")

Response Time Distribution

{
  "id": "latency-distribution",
  "type": "chart-histogram",
  "settings": {
    "height": "320px",
    "title": "API Response Time Distribution",
    "dataMode": "raw",
    "binCount": 20,
    "showMeanLine": true,
    "showMedianLine": true,
    "colors": ["#6c8cff"],
    "chartConfig": {
      "xAxis": { "label": "Response Time (ms)" },
      "yAxis": { "label": "Request Count" }
    },
    "binding": { "source": "$context", "path": "telemetry.responseTimes" }
  }
}

// Data: [{ "value": 42 }, { "value": 87 }, { "value": 156 }, ...]

Pre-Bucketed Score Distribution

When the server returns data already grouped into ranges, set dataMode: "bucketed" to use the labels and values as-is:

{
  "id": "score-distribution",
  "type": "chart-histogram",
  "settings": {
    "height": "300px",
    "title": "Customer Satisfaction Score Distribution",
    "dataMode": "bucketed",
    "barGap": "2%",
    "showFrequencyLine": true,
    "colors": ["#22c55e"],
    "chartConfig": {
      "xAxis": { "label": "NPS Score Range" },
      "yAxis": { "label": "Number of Responses" }
    },
    "binding": { "source": "$context", "path": "survey.scoreDistribution" }
  }
}

// Data:
// [
//   { "label": "0–20",  "value": 48  },
//   { "label": "21–40", "value": 112 },
//   { "label": "41–60", "value": 284 },
//   { "label": "61–80", "value": 431 },
//   { "label": "81–100","value": 293 }
// ]

Normalised Relative Frequency

Use normalize: true when comparing distributions across datasets of different sizes — the y-axis shows proportions (0–1) instead of raw counts:

{
  "id": "age-distribution",
  "type": "chart-histogram",
  "settings": {
    "height": "280px",
    "title": "Customer Age Distribution",
    "dataMode": "raw",
    "binCount": 15,
    "normalize": true,
    "chartConfig": {
      "xAxis": { "label": "Age" },
      "yAxis": { "label": "Relative Frequency" }
    },
    "binding": { "source": "$context", "path": "customers.ages" }
  }
}

Histogram vs Bar Chart

Property	Histogram	Bar Chart
Data type	Continuous numeric	Categorical / discrete
X-axis	Numeric range (bins)	Named categories
Bar gaps	No gap (adjacent)	Gap between bars
Y-axis	Frequency / count	Measure value
Use for	Distribution shape analysis	Category comparison

Bin Count Selection The optimal number of bins depends on your dataset size. A rule of thumb is the square root of the number of data points. For 100 points use 10 bins; for 400 points use 20 bins. Too few bins hide the shape; too many create noise.

← Scatter Plot Next: Heatmap →