Skip to content

excel chart scatter

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

Excel: Chart - scatter

A dedicated page for the scatter (XY) chart type. Scatter charts plot data points using numeric X and Y coordinates, making them ideal for correlation analysis, distribution plots, and scientific data. Unlike category-based charts, both axes are value axes, giving full numeric control over point placement.

Path: /{SheetName}/chart[N]

Add command shape:

officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop title="Correlation Analysis" \
  --prop categories="10,20,30,40,50" \
  --prop series1="Revenue:100,200,350,420,500" \
  <styling props>

See also: Chart - add, Chart - set, Chart - get.

Chart type variants

Type string Aliases Description
scatter xy XY scatter chart (style controlled by scatterStyle)

Scatter style

Property Default Notes
scatterStyle lineMarker Visual connection between points
Style Description
marker Points only (no connecting lines)
line Lines only (no markers)
lineMarker Lines with markers (default)
smooth Smooth curves only
smoothMarker Smooth curves with markers 
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop scatterStyle=smooth \
  --prop title="Correlation" \
  --prop categories="1,2,3,4,5" \
  --prop series1="Y:2,4,5,8,10"

officecli set data.xlsx /Sheet1/chart[1] --prop scatterStyle=marker

Data format

Scatter charts use numeric X values (from categories) and Y values (from series data). Both axes are value axes.

# X values as categories, Y values as series
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop categories="10,20,30,40,50" \
  --prop series1="Revenue:100,200,350,420,500" \
  --prop series2="Profit:20,50,80,100,130"

Line appearance

Scatter charts with scatterStyle=line, lineMarker, smooth, or smoothMarker render connecting lines between points. These lines support the same width and dash properties as line charts.

Line width

Property Default Notes
lineWidth 2 pt Line thickness in points. Applies to all series.
series{N}.lineWidth — Per-series override. E.g. series1.lineWidth=3

Internally stored as EMU (1 pt = 12,700 EMU) in a:ln/@w.

# Thick connecting lines
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop scatterStyle=lineMarker \
  --prop series1="Y:10,20,30" --prop categories="1,2,3" \
  --prop lineWidth=3

# Per-series widths via set
officecli set data.xlsx /Sheet1/chart[1] --prop series1.lineWidth=1 --prop series2.lineWidth=3

Line dash patterns

Property Default Notes
lineDash / dash solid Applies to all series
series{N}.lineDash — Per-series override
Dash value SVG equivalent Visual
solid none ————
dot / sysDot 1,2 . . . . .
dash / sysDash 5,3 - - - -
dashDot / sysDashDot 5,3,1,3 - . - .
longDash / lgDash 8,3 — — —
longDashDot / lgDashDot 8,3,1,3 — . — .
longDashDotDot / lgDashDotDot 8,3,1,3,1,3 — . . — . . 
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop scatterStyle=lineMarker \
  --prop series1="Measured:100,200,300" \
  --prop series2="Predicted:150,250,350" \
  --prop categories="10,20,30" \
  --prop lineDash=dash

# Mix: solid measured + dashed predicted
officecli set data.xlsx /Sheet1/chart[1] \
  --prop series1.lineDash=solid \
  --prop series2.lineDash=dash

Smooth curves

Property Default Notes
scatterStyle lineMarker Set to smooth or smoothMarker for spline interpolation

When scatterStyle is smooth or smoothMarker, data points are connected with Catmull-Rom cubic Bezier curves instead of straight line segments. The HTML preview faithfully renders the smooth path via SVG <path> with cubic Bezier commands.

officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop scatterStyle=smoothMarker \
  --prop series1="Trend:80,120,115,140,135,160" \
  --prop categories="1,2,3,4,5,6"

Transparency and opacity

Property Default Notes
transparency 0 Series transparency (0-100%)
opacity / alpha 100 Series opacity (0-100%) 
# Translucent lines for background context
officecli set data.xlsx /Sheet1/chart[1] --prop transparency=40

Markers

Property Default Notes
showMarker / showMarkers true Toggle marker visibility for the entire chart
marker / markers — Chart-level marker: "style", "style:size", or "style:size:color"
series{N}.marker — Per-series marker override
series{N}.markerSize — Per-series marker size

Marker styles

circle (default), diamond, square, triangle, star, x, plus, dash, dot, none

# Diamond markers, size 8
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop scatterStyle=marker \
  --prop series1="Data:10,20,30" --prop categories="1,2,3" \
  --prop marker="diamond:8"

# Per-series: circles for measured, triangles for predicted
officecli set data.xlsx /Sheet1/chart[1] \
  --prop series1.marker="circle:6:4472C4" \
  --prop series2.marker="triangle:6:ED7D31"

# Hide all markers (line-only style)
officecli set data.xlsx /Sheet1/chart[1] --prop showMarker=false

Title styling

Property Default Notes
title — Chart title text
title.font / titleFont — Font family
title.size / titleSize — Font size (pt)
title.color / titleColor — Font color (hex)
title.bold / titleBold — Bold (true/false)
title.glow / titleGlow — Glow: "COLOR-RADIUS-OPACITY" or "none"
title.shadow / titleShadow — Shadow: "COLOR-BLUR-ANGLE-DIST-OPACITY" or "none"

Legend

Property Default Notes
legend true Position: top, bottom, left, right, none
legend.overlay false Float legend on top of the chart
legendFont / legend.font — "size:color:fontname"

Axis features

Scale control

Property Default Notes
axisMin / min (auto) Value axis lower bound
axisMax / max (auto) Value axis upper bound
majorUnit (auto) Major gridline / tick interval
minorUnit (auto) Minor gridline / tick interval
axisNumFmt / axisNumberFormat General Number format for tick labels (e.g. "$#,##0", "0%")

Both axes in a scatter chart are value axes. axisMin/axisMax apply to the Y (value) axis. Use catAxisMin/catAxisMax if you need to constrain the X axis range.

# Lock Y axis to 0-600, gridlines every 100
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop series1="Data:95,120,280,420,500" \
  --prop categories="10,20,30,40,50" \
  --prop axisMin=0 --prop axisMax=600 --prop majorUnit=100

Logarithmic scale

Property Default Notes
logBase / logScale — Logarithmic scale base (e.g. 10)

Converts the value axis to logarithmic spacing. The HTML preview renders log-scale correctly with power-of-base tick marks.

officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop series1="Growth:1,10,100,1000,10000" \
  --prop categories="1,2,3,4,5" \
  --prop logBase=10

Reversed axis

Property Default Notes
axisOrientation / axisReverse minMax Set to maxMin or true to flip the Y axis 
# Inverted Y axis
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop series1="Depth:10,25,40,55" \
  --prop categories="1,2,3,4" \
  --prop axisReverse=true

Dual axis (secondary axis)

Property Default Notes
secondaryAxis / secondary — Comma-separated 1-based series indices for secondary Y axis 
# Revenue on left axis, growth rate on right axis
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop series1="Revenue:100,200,300,400" \
  --prop series2="Growth %:5,8,12,15" \
  --prop categories="10,20,30,40" \
  --prop secondaryAxis=2

Display units

Property Default Notes
dispUnits / displayUnits — thousands, millions, billions, etc.

Axis visibility and styling

Property Default Notes
axisVisible / axis.visible true Show/hide both axes
axisLine / axis.line — Value axis line: "color:width:dash"
catAxisLine — Category (X) axis line: "color:width:dash"
majorTickMark / majorTick — out, in, cross, none
minorTickMark / minorTick — Same as major tick
tickLabelPos nextTo nextTo, high, low, none

Gridlines

Property Default Notes
gridlines / majorGridlines true Toggle or configure: true, false/none, or "color:widthPt:dash"
minorGridlines false Same format as gridlines 
# Custom gridlines: light gray, thin, dotted
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop series1="Data:100,200,300" --prop categories="10,20,30" \
  --prop "gridlines=D0D0D0:0.5:sysDot" \
  --prop "minorGridlines=EEEEEE:0.3:sysDot"

Reference lines (target / threshold overlays)

Property Default Notes
referenceLine / refLine — value or "value:color:width:dash"

Reference lines are horizontal overlays drawn at a constant value. They appear in the legend and are rendered in the HTML preview with the correct dash pattern.

# Target line at 300 — red, dashed
officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop series1="Actual:120,200,280,350" \
  --prop categories="10,20,30,40" \
  --prop "referenceLine=300:FF0000:1.5:dash"

Fills and borders

Property Default Notes
plotFill / plotAreaFill — Plot area background: hex, gradient "C1-C2[:angle]", or "none"
chartFill / chartAreaFill — Chart area background
plotArea.border / plotBorder — Plot area outline: "color:width:dash" or "none"
chartArea.border / chartBorder — Chart area outline

Series shadow and outline

Property Default Notes
series.shadow / seriesShadow — "COLOR-BLUR-ANGLE-DIST-OPACITY" or "none"
series.outline / seriesOutline — "COLOR-WIDTH" e.g. "FFFFFF-0.5" or "none"

Data labels

Property Default Notes
dataLabels false Toggle data labels
labelPos / labelPosition — Position: center, insideEnd, insideBase, outsideEnd, top, bottom, left, right, bestFit
labelFont — "size:color:bold"
dataLabel{N}.text — Custom text for individual label
dataLabel{N}.x/y/w/h — Manual layout of individual label
dataLabel{N}.delete — Hide individual label
dataLabels.separator — Separator between label parts
dataLabels.numFmt — Number format for labels

Layout control

Property Default Notes
x, y 0 Chart position (column/row index)
width 8 Chart width (column units)
height 15 Chart height (row units)
plotArea.x/y/w/h — Manual plot area layout (0-1 decimal)
title.x/y/w/h — Manual title layout
legend.x/y/w/h — Manual legend layout

Full example: presentation-grade scatter chart

officecli add data.xlsx /Sheet1 --type chart \
  --prop chartType=scatter \
  --prop scatterStyle=smoothMarker \
  --prop title="Revenue vs Marketing Spend" \
  --prop title.size=16 --prop title.bold=true \
  --prop title.font="Arial" --prop title.color=1F2937 \
  --prop series1="Product A:100,200,350,420,500" \
  --prop series2="Product B:80,150,280,380,460" \
  --prop categories="10,20,30,40,50" \
  --prop colors="4472C4,ED7D31" \
  --prop lineWidth=2.5 \
  --prop marker="circle:6" \
  --prop "gridlines=E5E7EB:0.5:solid" \
  --prop "minorGridlines=F3F4F6:0.3:sysDot" \
  --prop axisMin=0 --prop axisMax=600 --prop majorUnit=100 \
  --prop plotFill=FAFBFC \
  --prop "referenceLine=400:FF0000:1:dash" \
  --prop legend=bottom \
  --prop "legendfont=9:6B7280:Arial" \
  --prop x=0 --prop y=0 --prop width=14 --prop height=20

HTML preview support

The officecli HTML preview (officecli view data.xlsx html) renders the following scatter chart features:

Feature Preview Notes
XY point rendering Yes Numeric X/Y axes
Line connections Yes For line/lineMarker styles
Smooth curves Yes Catmull-Rom to cubic Bezier <path>
Dash patterns Yes stroke-dasharray
Per-series line width Yes stroke-width from OOXML
Marker shapes Yes 10 shapes: circle, diamond, square, triangle, star, x, plus, dash, dot, none
Reference lines Yes Dashed overlays with legend entry
Log scale Yes Logarithmic Y axis spacing
Reversed axis Yes Inverted Y direction
Data labels Yes Value text near points
Custom axis scale Yes axisMin/axisMax/majorUnit
Gridlines Yes Color, width, dash from OOXML
Shadow effects No Decorative; not rendered
Glow effects No Decorative; not rendered

Known quirks

  • Both axes are value axes. Unlike line/bar charts, scatter charts have no category axis. The X axis is a value axis, so categories must contain numeric values.
  • scatterStyle controls smooth and markers. There is no separate smooth property for scatter charts; smoothing is determined by the scatterStyle value (smooth or smoothMarker).
  • Line properties require a line style. lineWidth and lineDash have no effect when scatterStyle=marker (points only, no lines).

Inspect an existing scatter chart

# List all charts
officecli query data.xlsx chart

# Inspect a specific chart
officecli get data.xlsx "/Sheet1/chart[1]"

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

See Also

Based on OfficeCLI v1.0.64

Clone this wiki locally