Skip to content

excel chart boxwhisker

Jump to bottom
zmworm edited this page Apr 29, 2026 · 16 revisions

Excel: Chart - boxWhisker

A dedicated page for the boxWhisker (box plot) chart type. Box-whisker charts are part of Excel's cx:chart (extended chart, Office 2016+) family. They display statistical distribution of data showing median, quartiles, whiskers (min/max), and outliers.

Path: /{SheetName}/chart[N]

Add command shape:

officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=boxWhisker \
  --prop series1="Name:v1,v2,v3,..." \
  <styling props>

See also: Chart - add, Chart - set, histogram for the full cx styling reference.

What a boxWhisker is

A box-whisker (box plot) chart takes raw numeric data and computes a five-number summary: minimum, Q1, median, Q3, maximum. The box spans Q1..Q3, whiskers extend to min/max (or 1.5x IQR with outliers shown as individual points). A mean marker (x) is shown by default. Box plots are ideal for comparing distributions across groups and spotting outliers.

officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=boxWhisker \
  --prop title="Score Distribution" \
  --prop series1="Scores:45,52,58,61,63,65,67,68,70,72,75,78,82,85,90,95,99"

BoxWhisker-specific properties

Property Default Notes
quartileMethod exclusive Statistical quartile calculation method
Value Description
exclusive Excludes median from quartile calculation (default, matches Excel)
inclusive Includes median in quartile calculation 
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=boxWhisker \
  --prop series1="Data:10,20,30,40,50,60,70,80,90" \
  --prop quartileMethod=inclusive

officecli set data.xlsx /Sheet1/chart[1] --prop quartileMethod=exclusive

Built-in series element visibilities

These are set at creation and not currently user-configurable:

Element Default Description
meanLine false Line connecting mean values across boxes
meanMarker true X marker at mean value
nonoutliers false Show non-outlier data points
outliers true Show outlier data points beyond 1.5x IQR

Multi-group series

Each seriesN creates its own cx:series block, so multi-group box plots render as separate boxes with distinct X-axis labels and per-group colors (via colors=). The series name is used as the X-axis category label.

officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=boxWhisker \
  --prop series1="Team A:45,52,58,61,63,65,67,68,70" \
  --prop series2="Team B:50,55,60,63,67,71,75,80,88" \
  --prop series3="Team C:40,48,52,58,62,66,70,74,82" \
  --prop colors="4472C4,ED7D31,70AD47"

Layout knobs

Property Default Notes
x / y 0 Top-left cell position (column / row index)
width 8 Chart width in column units
height 15 Chart height in row units
gapWidth (auto) Space between boxes (0..500)

Series colors

Property Default Notes
fill (theme) Single hex color for the box fill: "4472C4" or with #. Internally stored without #.
colors (theme) Comma-separated hex colors (one per series if multiple).
series.shadow / seriesshadow — Outer drop shadow on boxes: "COLOR-BLUR-ANGLE-DIST-OPACITY" (e.g. "000000-6-45-3-35") or "none" to remove

Axis titles and tick labels

The cx category axis is the bottom axis (box labels), the cx value axis is the left axis (numeric scale). cx accepts the same xAxisTitle / yAxisTitle spelling as regular cChart's catTitle / axisTitle aliases.

Property Default Notes
xAxisTitle — Category (bottom) axis title
yAxisTitle — Value (left) axis title
axisTitle.color — Color for both axis titles (cx can't split per-axis)
axisTitle.size — Font size for both axis titles, in pt
axisTitle.bold — Bold both axis titles (true/false)
axisTitle.font — Font family for both axis titles
axisfont / axis.font — Compound tick-label styling for both axes: "size:color:fontname", all fields optional. E.g. "10:6B7280:Helvetica Neue"
tickLabels true Show tick labels on the axes. Set false for a minimalist look.

Axis scaling (value axis)

All four map to cx:valScaling attributes. Useful when you want multiple box plots in a dashboard to share a Y scale.

Property Default Notes
axismin / min (auto) Value-axis lower bound (numeric)
axismax / max (auto) Value-axis upper bound (numeric)
majorunit (auto) Major gridline interval
minorunit (auto) Minor gridline interval 
# Lock Y axis to 0..100 with gridlines every 10
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=boxWhisker \
  --prop series1="Scores:45,52,58,61,63,65,67,68,70,72,75,78,82,85,90,95,99" \
  --prop axismin=0 --prop axismax=100 --prop majorunit=10

Axis visibility and spine styling

Property Default Notes
axis.visible / axisvisible true Hide both axes when false. axis.delete is the inverse alias.
cataxis.visible / cataxisvisible true Hide only the category (bottom) axis
valaxis.visible / valaxisvisible true Hide only the value (left) axis
axisline / axis.line — Spine outline shared by both axes: "color", "color:width", "color:width:dash", or "none"
cataxis.line / cataxisline — Category-axis-only spine (overrides axisline for cat)
valaxis.line / valaxisline — Value-axis-only spine (overrides axisline for val) 
# Minimal look: single thin gray spine, no category axis
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=boxWhisker \
  --prop series1="Data:10,20,30,40,50,60,70,80,90" \
  --prop "axisline=888888:1.25" \
  --prop cataxis.visible=false \
  --prop gridlines=false

Gridlines

Property Default Notes
gridlines / majorGridlines true Toggle value-axis major gridlines
gridlineColor / gridline.color — Value-axis gridline color (hex)
xGridlines false Toggle category-axis major gridlines (off by default to match Excel)
xGridlineColor / xGridline.color — Category-axis gridline color. Only applies when xGridlines=true.

Data labels

Property Default Notes
dataLabels false true draws statistical values on the chart
datalabels.numfmt / labelnumfmt — Excel format code for the label text: "0", "0.0", "0.00%", "#,##0", etc. 
# Show data labels with one decimal
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=boxWhisker \
  --prop series1="Data:10,20,30,40,50,60,70,80,90" \
  --prop dataLabels=true \
  --prop "datalabels.numfmt=0.0"

Title styling

Property Default Notes
title — Chart title text; none/false to hide
title.color / titlecolor — Title font color (hex)
title.size / titlesize — Title font size (pt)
title.bold / titlebold — Title bold (true/false)
title.font / titlefont — Title font family
title.shadow / titleshadow — Title drop shadow: "COLOR-BLUR-ANGLE-DIST-OPACITY" or "none"

Legend

Property Default Notes
legend — top / bottom / left / right / none (omit legend)
legend.overlay / legendoverlay false Let the legend float on top of the plot area when true. Useful when chart space is tight.
legendfont / legend.font — Compound legend text styling: "size:color:fontname"

Plot area and chart area fills

The plot area is the rectangle the boxes are drawn inside. The chart area is the outer frame that also contains the title, legend, and axis labels.

Property Default Notes
plotareafill / plotfill — Plot-area solid background: hex color
plotarea.border / plotborder — Plot-area outline: "color", "color:width", "color:width:dash", or "none"
chartareafill / chartfill — Chart-area (outer frame) solid background: hex color
chartarea.border / chartborder — Chart-area outline, same grammar as plotarea.border 
# "Card" look — light plot area with a subtle border
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=boxWhisker \
  --prop series1="Data:10,20,30,40,50,60,70,80,90" \
  --prop plotareafill=FAFBFC \
  --prop "plotarea.border=D0D7DE:1" \
  --prop chartareafill=FFFFFF \
  --prop "chartarea.border=E5E5E5:0.75"

Full example: presentation-grade box plot

officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=boxWhisker \
  --prop title="Response Time Distribution (ms)" \
  --prop title.color=1B2838 --prop title.size=18 --prop title.bold=true \
  --prop title.font="Helvetica Neue" \
  --prop "title.shadow=000000-6-45-3-50" \
  --prop series1="Latency:12,18,22,25,28,30,32,35,38,40,42,45,55,62,78,95,120" \
  --prop quartileMethod=exclusive \
  --prop fill=5B9BD5 --prop "series.shadow=000000-6-45-3-35" \
  --prop axismin=0 --prop axismax=130 --prop majorunit=10 \
  --prop xAxisTitle="Service" --prop yAxisTitle="Latency (ms)" \
  --prop axisTitle.color=4A5568 --prop axisTitle.size=12 \
  --prop axisTitle.bold=true --prop axisTitle.font="Helvetica Neue" \
  --prop "axisfont=10:6B7280:Helvetica Neue" \
  --prop "axisline=CBD5E1:1.25" \
  --prop gridlineColor=E2E8F0 \
  --prop plotareafill=F8FAFC \
  --prop "plotarea.border=E2E8F0:1" \
  --prop chartareafill=FFFFFF \
  --prop "chartarea.border=CBD5E1:0.75" \
  --prop dataLabels=true --prop "datalabels.numfmt=0" \
  --prop legend=top \
  --prop "legendfont=10:64748B:Helvetica Neue" \
  --prop x=0 --prop y=0 --prop width=16 --prop height=22

HTML preview support

Feature Preview Notes
Box-whisker rendering Yes Q1/Q3 box, median line, whiskers extend to last non-outlier within 1.5×IQR, outliers as open circles, mean as × marker; Y scale auto-padded 5% so edge outliers are not clipped

Known quirks and limitations

  • quartileMethod default is exclusive. This matches Excel's default behavior. The inclusive method includes the median in both Q1 and Q3 calculations, producing slightly different whisker positions.
  • axisTitle.* styles BOTH axis titles. cx doesn't split X/Y title styling into separate knob namespaces — set axisTitle.color=... and both X and Y titles inherit the same run properties. This is an Excel limitation, not an officecli one.
  • Built-in visibilities are not user-configurable. meanLine, meanMarker, nonoutliers, and outliers are set at creation time. Future versions may expose these as Set properties.
  • Preview font fallback. The HTML preview does not reproduce custom axis-label font families — tick labels fall back to the preview's default sans font.

Inspect an existing boxWhisker

# Count all charts across the workbook
officecli query data.xlsx chart

# Introspect a single chart's bound properties
officecli get data.xlsx "/Sheet1/chart[1]"

# Render the sheet to HTML preview
officecli view data.xlsx html > preview.html

See Also

  • Chart — Overview of chart operations
  • Chart add — Generic chart add (all 17 types)
  • Chart set — Modify existing charts (incl. boxWhisker)
  • Chart get — Read back chart properties
  • histogram — Related statistical chart
  • funnel — Shared cx vocabulary
  • treemap — Hierarchical area

Based on OfficeCLI v1.0.64

Clone this wiki locally