iofficeai--officecli/examples/excel/charts/charts-basic.md

Basic Charts Showcase

This demo consists of three files that work together:

• charts-basic.py — Python script that calls officecli commands to generate the workbook. Each chart command is shown as a copyable shell command in the comments, then executed by the script.
• charts-basic.xlsx — The generated workbook with 8 sheets (1 data + 7 chart sheets, 28 charts total). Open in Excel to see the rendered charts.
• charts-basic.md — This file. Maps each sheet to the features it demonstrates.

Regenerate

cd examples/excel
python3 charts-basic.py
# → charts-basic.xlsx

Source Data

Sheet1: 12 months of regional sales data (East, South, North, West) used by all charts.

Chart Sheets

Sheet: 1-Column Charts

Four column chart variants demonstrating the column family.

# Basic clustered column with axis titles and axis font
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=column \
  --prop title="Regional Sales" \
  --prop dataRange=Sheet1!A1:E13 \
  --prop catTitle=Month --prop axisTitle=Sales \
  --prop axisfont=9:58626E:Arial \
  --prop gridlines=D9D9D9:0.5:dot

# Stacked column with custom colors, data labels, gap control, series outline
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=columnStacked \
  --prop colors=2E75B6,70AD47,FFC000,C00000 \
  --prop dataLabels=true --prop labelPos=center \
  --prop gapwidth=60 \
  --prop series.outline=FFFFFF-0.5

# 100% stacked with legend positioning and plot fill
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=columnPercentStacked \
  --prop legend=bottom --prop legendfont=9:8B949E \
  --prop plotFill=F5F5F5

# 3D column with perspective and title styling
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=column3d \
  --prop view3d=15,20,30 \
  --prop title.font=Calibri --prop title.size=16 \
  --prop title.color=1F4E79 --prop title.bold=true

Features: column, columnStacked, columnPercentStacked, column3d, dataRange, catTitle, axisTitle, axisfont, gridlines, colors, dataLabels, labelPos, gapwidth, series.outline, legend, legendfont, plotFill, view3d, title.font/size/color/bold

Sheet: 2-Bar Charts

Four horizontal bar chart variants.

# Horizontal bar with inline data and gap control
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=bar \
  --prop 'data=East:198;South:158;North:142;West:180' \
  --prop gapwidth=80 \
  --prop dataLabels=true --prop labelPos=outsideEnd

# Stacked bar with named series and overlap
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=barStacked \
  --prop series1=H1:663,598,528,661 \
  --prop series2=H2:833,718,669,868 \
  --prop gapwidth=50 --prop overlap=0

# 100% stacked bar with reference line and axis lines
# Note: value axis of a barPercentStacked chart is 0-1 (= 0%-100%), so a 50% line = 0.5
# referenceLine forms: value | value:color | value:color:label | value:color:width:dash
#                      | value:color:label:dash | value:color:width:dash:label
# Width is in points (default 1.5pt). e.g. 0.5:FF0000:2:dash draws a 2pt dashed line.
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=barPercentStacked \
  --prop referenceLine=0.5:FF0000:Target:dash \
  --prop axisLine=333333:1:solid \
  --prop catAxisLine=333333:1:solid

# 3D bar with chart area fill and preset style
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=bar3d \
  --prop view3d=10,30,20 \
  --prop chartFill=F2F2F2 \
  --prop style=3

Features: bar, barStacked, barPercentStacked, bar3d, inline data, named series, gapwidth, overlap, labelPos=outsideEnd, referenceLine, axisLine, catAxisLine, chartFill, style

Sheet: 3-Line Charts

Four line chart variants with markers, smoothing, and data tables.

# Line with cell-range series (dotted syntax) and markers
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=line \
  --prop series1.name=East \
  --prop series1.values=Sheet1!B2:B13 \
  --prop series1.categories=Sheet1!A2:A13 \
  --prop showMarkers=true --prop marker=circle:6:2E75B6 \
  --prop gridlines=D9D9D9:0.5:dot \
  --prop minorGridlines=EEEEEE:0.3:dot

# Smooth line with series shadow
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=line \
  --prop smooth=true --prop lineWidth=2.5 \
  --prop gridlines=none \
  --prop series.shadow=000000-4-315-2-40

# Stacked line with tick marks
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=lineStacked \
  --prop majorTickMark=outside --prop tickLabelPos=low

# Dashed line with data table and hidden legend
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=line \
  --prop lineDash=dash --prop lineWidth=1.5 \
  --prop dataTable=true --prop legend=none

Features: series1.name/values/categories (cell range), showMarkers, marker (style:size:color), smooth, lineWidth, lineDash, gridlines, minorGridlines, series.shadow, lineStacked, majorTickMark, tickLabelPos, dataTable, legend=none

Sheet: 4-Area Charts

Four area chart variants with transparency and gradients.

# Area with transparency and gradient
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=area \
  --prop transparency=40 \
  --prop gradient=4472C4-BDD7EE:90

# Stacked area with plot fill and rounded corners
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=areaStacked \
  --prop plotFill=F5F5F5 --prop roundedCorners=true

# 100% stacked area with axis visibility control
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=areaPercentStacked \
  --prop axisVisible=true --prop axisLine=999999:0.5:solid

# 3D area with perspective
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=area3d \
  --prop view3d=20,25,15

Features: area, areaStacked, areaPercentStacked, area3d, transparency, gradient, plotFill, roundedCorners, axisVisible, axisLine

Sheet: 5-Styling

Demonstrates styling and formatting properties on various charts.

# Fully styled chart: title effects, legend, axis fonts, series effects
officecli add data.xlsx /Sheet --type chart \
  --prop title.font=Georgia --prop title.size=18 \
  --prop title.color=1F4E79 --prop title.bold=true \
  --prop title.shadow=000000-3-315-2-30 \
  --prop legendfont=10:444444:Helvetica --prop legend=right \
  --prop axisfont=9:58626E:Arial \
  --prop series.outline=FFFFFF-0.5 \
  --prop series.shadow=000000-3-315-2-25 \
  --prop roundedCorners=true --prop referenceLine=160:FF0000:1:dash

# Dual Y-axis (secondary axis)
officecli add data.xlsx /Sheet --type chart \
  --prop secondaryAxis=2

# Per-point coloring and negative value inversion
officecli add data.xlsx /Sheet --type chart \
  --prop point1.color=70AD47 --prop point3.color=FF0000 \
  --prop invertIfNeg=true

# Gradient plot fill and custom data label text
officecli add data.xlsx /Sheet --type chart \
  --prop plotFill=E8F0FE-FFFFFF:90 \
  --prop marker=diamond:8:4472C4 \
  --prop dataLabels.numFmt=#,##0 \
  --prop dataLabel3.text=Peak!

Features: title.shadow, secondaryAxis, point{N}.color, invertIfNeg, plotFill gradient, dataLabels.numFmt, dataLabel{N}.text

Sheet: 6-Layout

Manual positioning and axis control properties.

# Manual layout of plot area, title, legend
officecli add data.xlsx /Sheet --type chart \
  --prop plotArea.x=0.15 --prop plotArea.y=0.15 \
  --prop plotArea.w=0.7 --prop plotArea.h=0.7 \
  --prop title.x=0.3 --prop title.y=0.01 \
  --prop legend.x=0.02 --prop legend.y=0.4 \
  --prop legend.overlay=true

# Logarithmic scale, reversed axis, display units
officecli add data.xlsx /Sheet --type chart \
  --prop logBase=10 \
  --prop axisOrientation=maxMin \
  --prop dispUnits=thousands

# Label font, separator, per-label hide
officecli add data.xlsx /Sheet --type chart \
  --prop labelFont=11:2E75B6:true \
  --prop "dataLabels.separator=: " \
  --prop dataLabel2.text=Best! \
  --prop dataLabel3.delete=true

# Error bars, minor ticks, opacity
officecli add data.xlsx /Sheet --type chart \
  --prop errBars=percentage \
  --prop majorTickMark=outside --prop minorTickMark=inside \
  --prop opacity=80

Features: plotArea.x/y/w/h, title.x/y, legend.x/y, legend.overlay, logBase, axisOrientation, dispUnits, labelFont, dataLabels.separator, dataLabel{N}.delete, errBars, minorTickMark, opacity

Sheet: 7-Effects

Visual effects: gradients, conditional colors, glow, presets.

# Per-series gradients
officecli add data.xlsx /Sheet --type chart \
  --prop 'gradients=4472C4-BDD7EE:90;ED7D31-FBE5D6:90'

# Area fill gradient and title glow
officecli add data.xlsx /Sheet --type chart \
  --prop areafill=4472C4-BDD7EE:90 \
  --prop title.glow=4472C4-8-60

# Conditional coloring (below/above threshold)
officecli add data.xlsx /Sheet --type chart \
  --prop colorRule=60:FF0000:70AD47

# Preset style and leader lines
officecli add data.xlsx /Sheet --type chart \
  --prop style=26 \
  --prop dataLabels.showLeaderLines=true

Features: gradients, areafill, title.glow, colorRule, style, dataLabels.showLeaderLines

Inspect the Generated File

officecli query charts-basic.xlsx chart
officecli get charts-basic.xlsx "/1-Column Charts/chart[1]"