pptx API

This reference covers the Office.js-compatible PowerPoint surface exposed by witan pptx exec. TypeScript or JavaScript scripts run headlessly against a PPTX file through PowerPoint.run and the Witan PPTX runtime. Microsoft Office does not need to be installed.

Witan implements an Office.js-compatible PowerPoint superset for headless PPTX automation. It follows Office.js object model semantics where compatible and adds chart APIs that upstream PowerPoint Office.js does not expose. Unsupported members throw explicit Office.js-style errors rather than silently doing nothing.

Call Shape

witan pptx exec deck.pptx --stdin <<'JS'
return await PowerPoint.run(async context => {
  const slide = context.presentation.slides.getItemAt(0);
  const count = context.presentation.slides.getCount();
  await context.sync();
  return { firstSlideId: slide.id, slideCount: count.value };
});
JS

OfficeExtension.ClientResult<T> values, such as getCount(), should be read after await context.sync(). In Witan's headless runtime, load(...) and sync() are compatibility calls rather than network round trips: load(...) records requested properties, and sync() provides the Office.js sequencing point while resolving against the in-memory presentation model.

Runtime Boundaries

• PowerPoint.createPresentation(...) is intentionally not implemented. Use witan pptx exec <file.pptx> --create --save.
• Top-level await is supported.
• Static and dynamic imports are not available.
• Scripts cannot access the filesystem or network.
• --input-json is exposed as the global input; --input-file key=@path adds PNG/JPEG data URIs under input[key].
• The public CLI surface is witan pptx exec, witan pptx exec-types, witan pptx lint, and witan pptx render; the backend RPC operations are implementation details.

Objects returned by the runtime remain live while their underlying presentation object exists. After deleting or structurally replacing an object, reacquire it from its collection before reading or writing it again. Use getItemOrNullObject(...) and related null-object methods when absence is expected; using a stale object raises an Office.js-style error.

Implemented Surface Summary

Runtime

Presentation, slides, layouts, and masters

Backgrounds and themes

Shapes, images, and groups

Text and hyperlinks

Tables

Metadata and custom data

Charts

Witan Chart Extensions

These members are Witan extensions for PowerPoint presentations. They use Excel-style chart semantics adapted to PPTX chart parts and embedded chart workbooks.

Chart Enums

ChartType

Specifies the type of a chart.

area = "Area", areaStacked = "AreaStacked", areaStacked100 = "AreaStacked100", barClustered = "BarClustered", barStacked = "BarStacked", barStacked100 = "BarStacked100", bubble = "Bubble", boxwhisker = "Boxwhisker", columnClustered = "ColumnClustered", columnStacked = "ColumnStacked", columnStacked100 = "ColumnStacked100", doughnut = "Doughnut", funnel = "Funnel", histogram = "Histogram", line = "Line", lineMarkers = "LineMarkers", lineMarkersStacked = "LineMarkersStacked", lineMarkersStacked100 = "LineMarkersStacked100", lineStacked = "LineStacked", lineStacked100 = "LineStacked100", pareto = "Pareto", pie = "Pie", radar = "Radar", radarFilled = "RadarFilled", radarMarkers = "RadarMarkers", stockHLC = "StockHLC", stockOHLC = "StockOHLC", stockVHLC = "StockVHLC", stockVOHLC = "StockVOHLC", surfaceTopView = "SurfaceTopView", surfaceTopViewWireframe = "SurfaceTopViewWireframe", waterfall = "Waterfall", xyScatter = "XYScatter", xyScatterLines = "XYScatterLines", xyScatterLinesNoMarkers = "XYScatterLinesNoMarkers", xyScatterSmooth = "XYScatterSmooth", xyScatterSmoothNoMarkers = "XYScatterSmoothNoMarkers"

ChartAxisCategoryType

Specifies the type of a category axis.

automatic = "Automatic", textAxis = "TextAxis", dateAxis = "DateAxis"

ChartAxisGroup

Specifies whether a chart axis or series is primary or secondary.

primary = "Primary", secondary = "Secondary"

ChartAxisTimeUnit

Specifies the time unit used by a date axis.

days = "Days", months = "Months", years = "Years"

ChartBinType

Specifies how bins are configured for histogram and Pareto charts.

category = "Category", auto = "Auto", binWidth = "BinWidth", binCount = "BinCount"

ChartBoxQuartileCalculation

Specifies the quartile calculation type for box and whisker charts.

inclusive = "Inclusive", exclusive = "Exclusive"

ChartAxisType

Specifies the type of chart axis.

category = "Category", invalid = "Invalid", value = "Value"

ChartDataLabelPosition

Specifies the position of chart data labels.

bestFit = "BestFit", bottom = "Bottom", center = "Center", insideBase = "InsideBase", insideEnd = "InsideEnd", left = "Left", outsideEnd = "OutsideEnd", right = "Right", top = "Top"

ChartDataSourceType

Specifies the source type for chart series data.

localRange = "LocalRange"

ChartDisplayBlanksAs

Specifies how blank cells are plotted on a chart.

notPlotted = "NotPlotted", zero = "Zero", interplotted = "Interplotted"

ChartLegendPosition

Specifies the position of a chart legend.

bottom = "Bottom", corner = "Corner", left = "Left", right = "Right", top = "Top"

ChartLineStyle

Specifies the line style for chart borders and line formats.

automatic = "Automatic", continuous = "Continuous", dash = "Dash", dashDot = "DashDot", dashDotDot = "DashDotDot", dot = "Dot", none = "None", roundDot = "RoundDot"

ChartMarkerStyle

Specifies the marker style for a chart series.

automatic = "Automatic", circle = "Circle", dash = "Dash", diamond = "Diamond", dot = "Dot", none = "None", picture = "Picture", plus = "Plus", square = "Square", star = "Star", triangle = "Triangle", x = "X"

ChartUnderlineStyle

Specifies the underline style for chart font text.

none = "None", single = "Single"

ChartSeriesBy

Specifies whether chart data series are read by rows, columns, or inferred automatically.

auto = "Auto", columns = "Columns", rows = "Rows"

ChartSeriesDimension

Specifies a dimension of chart series data.

categories = "Categories", values = "Values", xvalues = "XValues", yvalues = "YValues", bubbleSizes = "BubbleSizes"

Chart Types and Interfaces

ShapeAddChartOptions

Represents the options used when adding a chart to a slide.

ChartSetDataOptions

Represents the options used when replacing chart data.

ChartSetDataRangeOptions

Represents the options used when repointing chart data to an embedded workbook range.

ChartUpdateData

An interface for updating data on the chart object.

ChartAxesUpdateData

An interface for updating data on the chart axes object.

ChartAxisUpdateData

An interface for updating data on the chart axis object.

ChartAxisTitleUpdateData

An interface for updating data on the chart axis title object.

ChartGridlinesUpdateData

An interface for updating data on the chart gridlines object.

ChartAreaFormatUpdateData

An interface for updating data on the chart area format object.

ChartBorderUpdateData

An interface for updating data on the chart border object.

ChartFontUpdateData

An interface for updating data on the chart font object.

ChartDataLabelFormatUpdateData

An interface for updating data on the chart data label format object.

ChartDataLabelsUpdateData

An interface for updating data on the chart data labels object.

ChartLegendUpdateData

An interface for updating data on the chart legend object.

ChartLineFormatUpdateData

An interface for updating data on the chart line format object.

ChartPlotAreaUpdateData

An interface for updating data on the chart plot area object.

ChartPlotAreaFormatUpdateData

An interface for updating data on the chart plot area format object.

ChartSeriesCollectionUpdateData

An interface for updating data on a chart series collection.

ChartSeriesUpdateData

An interface for updating data on the chart series object.

ChartSeriesFormatUpdateData

An interface for updating data on the chart series format object.

ChartTitleUpdateData

An interface for updating data on the chart title object.

ChartData

An interface describing the data returned by calling chart.toJSON().

ChartAxesData

An interface describing the data returned by calling chartAxes.toJSON().

ChartAxisData

An interface describing the data returned by calling chartAxis.toJSON().

ChartAxisTitleData

An interface describing the data returned by calling chartAxisTitle.toJSON().

ChartBinOptionsData

An interface describing the data returned by calling chartBinOptions.toJSON().

ChartBoxwhiskerOptionsData

An interface describing the data returned by calling chartBoxwhiskerOptions.toJSON().

ChartGridlinesData

An interface describing the data returned by calling chartGridlines.toJSON().

ChartAreaFormatData

An interface describing the data returned by calling chartAreaFormat.toJSON().

ChartBorderData

An interface describing the data returned by calling chartBorder.toJSON().

ChartFontData

An interface describing the data returned by calling chartFont.toJSON().

ChartDataLabelFormatData

An interface describing the data returned by calling chartDataLabelFormat.toJSON().

ChartDataLabelsData

An interface describing the data returned by calling chartDataLabels.toJSON().

ChartLegendData

An interface describing the data returned by calling chartLegend.toJSON().

ChartLineFormatData

An interface describing the data returned by calling chartLineFormat.toJSON().

ChartPlotAreaData

An interface describing the data returned by calling chartPlotArea.toJSON().

ChartPlotAreaFormatData

An interface describing the data returned by calling chartPlotAreaFormat.toJSON().

ChartSeriesCollectionData

An interface describing the data returned by calling chartSeriesCollection.toJSON().

ChartSeriesData

An interface describing the data returned by calling chartSeries.toJSON().

ChartSeriesFormatData

An interface describing the data returned by calling chartSeriesFormat.toJSON().

ChartTitleData

An interface describing the data returned by calling chartTitle.toJSON().

ChartLoadOptions

Represents the properties to load on a chart.

ChartAxesLoadOptions

Represents the properties to load on chart axes.

ChartAxisLoadOptions

Represents the properties to load on a chart axis.

ChartAxisTitleLoadOptions

Represents the properties to load on a chart axis title.

ChartGridlinesLoadOptions

Represents the properties to load on chart gridlines.

ChartAreaFormatLoadOptions

Represents the properties to load on a chart area format.

ChartBorderLoadOptions

Represents the properties to load on a chart border.

ChartFontLoadOptions

Represents the properties to load on a chart font.

ChartDataLabelFormatLoadOptions

Represents the properties to load on a chart data label format.

ChartDataLabelsLoadOptions

Represents the properties to load on chart data labels.

ChartLegendLoadOptions

Represents the properties to load on a chart legend.

ChartLineFormatLoadOptions

Represents the properties to load on a chart line format.

ChartPlotAreaLoadOptions

Represents the properties to load on a chart plot area.

ChartPlotAreaFormatLoadOptions

Represents the properties to load on a chart plot area format.

ChartSeriesCollectionLoadOptions

Represents the properties to load for each item in a chart series collection.

ChartSeriesLoadOptions

Represents the properties to load on a chart series.

ChartBinOptionsLoadOptions

Represents the properties to load on chart bin options.

ChartBoxwhiskerOptionsLoadOptions

Represents the properties to load on chart box and whisker options.

ChartSeriesFormatLoadOptions

Represents the properties to load on a chart series format.

ChartTitleLoadOptions

Represents the properties to load on a chart title.

Object Reference

PowerPoint

Properties:

• BindingType
• BulletStyle
• BulletType
• ChartAxisCategoryType
• ChartAxisGroup
• ChartAxisTimeUnit
• ChartAxisType
• ChartBinType
• ChartBoxQuartileCalculation
• ChartDataLabelPosition
• ChartDataSourceType
• ChartDisplayBlanksAs
• ChartLegendPosition
• ChartLineStyle
• ChartMarkerStyle
• ChartSeriesBy
• ChartSeriesDimension
• ChartType
• ChartUnderlineStyle
• ConnectorType
• DocumentPropertyType
• ErrorCodes
• GeometricShapeType
• HyperlinkType
• InsertSlideFormatting
• LabelingCapability
• ParagraphHorizontalAlignment
• PlaceholderType
• RequestContext
• SensitivityLabelProtectionType
• SensitivityLabelUpdateResult
• ShapeAutoSize
• ShapeFillType
• ShapeFontUnderlineStyle
• ShapeGetImageFormatType
• ShapeLineDashStyle
• ShapeLineStyle
• ShapeType
• ShapeZOrder
• SlideBackgroundFillType
• SlideBackgroundGradientFillType
• SlideBackgroundPatternFillType
• SlideLayoutType
• TableStyle
• TextVerticalAlignment
• ThemeColor

Methods:

• createPresentation(...)
• run(...)

RequestContext

Properties:

• application
• debugInfo
• presentation
• requestHeaders
• sensitivityLabelsCatalog
• trackedObjects

Methods:

• loadRecursive(...)
• sync(...)
• trace(...)

Application

Methods:

• newObject(...)

Presentation

Properties:

• bindings
• customXmlParts
• id
• onSlideSelectionChanged
• pageSetup
• properties
• sensitivityLabel
• slideMasters
• slides
• tags
• title

Methods:

• getActiveSlideOrNullObject(...)
• getSelectedShapes(...)
• getSelectedSlides(...)
• getSelectedTextRange(...)
• getSelectedTextRangeOrNullObject(...)
• insertSlidesFromBase64(...)
• setSelectedSlides(...)

SlideCollection

Properties:

• items

Methods:

• add(...)
• exportAsBase64Presentation(...)
• getCount(...)
• getItem(...)
• getItemAt(...)
• getItemOrNullObject(...)

Slide

Properties:

• background
• customXmlParts
• hyperlinks
• id
• index
• layout
• shapes
• slideMaster
• tags
• themeColorScheme

Methods:

• applyLayout(...)
• delete(...)
• exportAsBase64(...)
• getImageAsBase64(...)
• moveTo(...)
• setSelectedShapes(...)

SlideScopedCollection

Properties:

• items

Methods:

• exportAsBase64Presentation(...)
• getCount(...)
• getItem(...)
• getItemAt(...)
• getItemOrNullObject(...)

SlideMasterCollection

Properties:

• items

Methods:

• getCount(...)
• getItem(...)
• getItemAt(...)
• getItemOrNullObject(...)

SlideMaster

Properties:

• background
• customXmlParts
• id
• layouts
• name
• shapes
• themeColorScheme

Methods:

• delete(...)

SlideLayoutCollection

Properties:

• items

Methods:

• getCount(...)
• getItem(...)
• getItemAt(...)
• getItemOrNullObject(...)

SlideLayout

Properties:

• background
• customXmlParts
• id
• name
• shapes
• themeColorScheme
• type

Methods:

• delete(...)

SlideBackground

Properties:

• areBackgroundGraphicsHidden
• fill
• isMasterBackgroundFollowed

Methods:

• reset(...)

SlideBackgroundFill

Properties:

• type

Methods:

• getGradientFillOrNullObject(...)
• getPatternFillOrNullObject(...)
• getPictureOrTextureFillOrNullObject(...)
• getSolidFillOrNullObject(...)
• setGradientFill(...)
• setPatternFill(...)
• setPictureOrTextureFill(...)
• setSolidFill(...)

SlideBackgroundSolidFill

Properties:

• color
• transparency

SlideBackgroundGradientFill

Properties:

• type

SlideBackgroundPatternFill

Properties:

• backgroundColor
• foregroundColor
• pattern

SlideBackgroundPictureOrTextureFill

Properties:

• transparency

Methods:

• setImage(...)

SlideMasterBackground

Properties:

• fill

SlideLayoutBackground

Properties:

• areBackgroundGraphicsHidden
• fill
• isMasterBackgroundFollowed

Methods:

• reset(...)

ShapeCollection

Properties:

• items

Methods:

• addChart(...)
• addGeometricShape(...)
• addGroup(...)
• addLine(...)
• addPicture(...)
• addTable(...)
• addTextBox(...)
• getCount(...)
• getItem(...)
• getItemAt(...)
• getItemOrNullObject(...)

ShapeScopedCollection

Properties:

• items

Methods:

• getCount(...)
• getItem(...)
• getItemAt(...)
• getItemOrNullObject(...)
• group(...)

Shape

Properties:

• adjustments
• altTextDescription
• altTextTitle
• creationId
• customXmlParts
• fill
• group
• height
• id
• isDecorative
• left
• level
• lineFormat
• name
• parentGroup
• placeholderFormat
• rotation
• tags
• textFrame
• top
• type
• visible
• width
• zOrderPosition

Methods:

• delete(...)
• getChart(...)
• getChartOrNullObject(...)
• getGraphicOrNullObject(...)
• getImageAsBase64(...)
• getParentSlide(...)
• getParentSlideLayout(...)
• getParentSlideLayoutOrNullObject(...)
• getParentSlideMaster(...)
• getParentSlideMasterOrNullObject(...)
• getParentSlideOrNullObject(...)
• getTable(...)
• getTextFrameOrNullObject(...)
• setHyperlink(...)
• setZOrder(...)

ShapeGroup

Properties:

• creationId
• id
• shape
• shapes

Methods:

• ungroup(...)

Graphic

Properties:

• shape

Methods:

• convertToShape(...)

Adjustments

Properties:

• count

Methods:

• get(...)
• set(...)

ShapeFill

Properties:

• foregroundColor
• transparency
• type

Methods:

• clear(...)
• setImage(...)
• setSolidColor(...)

ShapeLineFormat

Properties:

• color
• dashStyle
• style
• transparency
• visible
• weight

TextFrame

Properties:

• autoSizeSetting
• bottomMargin
• hasText
• leftMargin
• rightMargin
• textRange
• topMargin
• verticalAlignment
• wordWrap

Methods:

• deleteText(...)
• getParentShape(...)

TextRange

Properties:

• font
• hyperlinks
• length
• paragraphFormat
• start
• text

Methods:

• getParentTextFrame(...)
• getSubstring(...)
• setHyperlink(...)
• setSelected(...)

ShapeFont

Properties:

• allCaps
• bold
• color
• doubleStrikethrough
• italic
• name
• size
• smallCaps
• strikethrough
• subscript
• superscript
• underline

ParagraphFormat

Properties:

• bulletFormat
• horizontalAlignment
• indentLevel

BulletFormat

Properties:

• style
• type
• visible

HyperlinkCollection

Properties:

• items

Methods:

• add(...)
• getCount(...)
• getItemAt(...)

HyperlinkScopedCollection

Properties:

• items

Methods:

• getCount(...)
• getItemAt(...)

Hyperlink

Properties:

• address
• screenTip
• type

Methods:

• delete(...)
• getLinkedShapeOrNullObject(...)
• getLinkedTextRangeOrNullObject(...)

Table

Properties:

• columnCount
• columns
• rowCount
• rows
• styleSettings
• values

Methods:

• clear(...)
• getCellOrNullObject(...)
• getMergedAreas(...)
• getShape(...)
• mergeCells(...)

TableRowCollection

Properties:

• items

Methods:

• add(...)
• deleteRows(...)
• getCount(...)
• getItemAt(...)

TableRow

Properties:

• currentHeight
• height
• rowIndex

Methods:

• delete(...)

TableColumnCollection

Properties:

• items

Methods:

• add(...)
• deleteColumns(...)
• getCount(...)
• getItemAt(...)

TableColumn

Properties:

• columnIndex
• width

Methods:

• delete(...)

TableCellCollection

Properties:

• items

Methods:

• getCount(...)
• getItemAtOrNullObject(...)

TableCell

Properties:

• borders
• columnCount
• columnIndex
• fill
• font
• horizontalAlignment
• indentLevel
• margins
• rowCount
• rowIndex
• text
• textRuns
• verticalAlignment

Methods:

• resize(...)
• split(...)

TableStyleSettings

Properties:

• areColumnsBanded
• areRowsBanded
• isFirstColumnHighlighted
• isFirstRowHighlighted
• isLastColumnHighlighted
• isLastRowHighlighted
• style

Borders

Properties:

• bottom
• diagonalDown
• diagonalUp
• left
• right
• top

Border

Properties:

• color
• dashStyle
• transparency
• weight

Margins

Properties:

• bottom
• left
• right
• top

DocumentProperties

Properties:

• author
• category
• comments
• company
• creationDate
• customProperties
• keywords
• lastAuthor
• manager
• revisionNumber
• subject
• title

CustomPropertyCollection

Properties:

• items

Methods:

• add(...)
• deleteAll(...)
• getCount(...)
• getItem(...)
• getItemAt(...)
• getItemOrNullObject(...)

CustomProperty

Properties:

• key
• type
• value

Methods:

• delete(...)

CustomXmlPartCollection

Properties:

• items

Methods:

• add(...)
• getByNamespace(...)
• getCount(...)
• getItem(...)
• getItemAt(...)
• getItemOrNullObject(...)

CustomXmlPartScopedCollection

Properties:

• items

Methods:

• getCount(...)
• getItem(...)
• getItemAt(...)
• getItemOrNullObject(...)
• getOnlyItem(...)
• getOnlyItemOrNullObject(...)

CustomXmlPart

Properties:

• id
• namespaceUri

Methods:

• delete(...)
• getXml(...)
• setXml(...)

TagCollection

Properties:

• items

Methods:

• add(...)
• delete(...)
• getCount(...)
• getItem(...)
• getItemAt(...)
• getItemOrNullObject(...)

Tag

Properties:

• key
• value

BindingCollection

Properties:

• items

Methods:

• add(...)
• addFromSelection(...)
• getCount(...)
• getItem(...)
• getItemAt(...)
• getItemOrNullObject(...)

Binding

Properties:

• id
• type

Methods:

• delete(...)
• getShape(...)

PageSetup

Properties:

• slideHeight
• slideWidth

ThemeColorScheme

Methods:

• getThemeColor(...)
• setThemeColor(...)

PlaceholderFormat

Properties:

• containedType
• type

SensitivityLabel

Methods:

• getCurrentOrNullObject(...)
• tryToUpdate(...)

SensitivityLabelsCatalog

Properties:

• getLabelingCapability

Methods:

• getLabels(...)
• newObject(...)

SensitivityLabelDetails

Properties:

• children
• color
• id
• isEnabled
• isNullObject
• name
• order
• protectionType
• siteId
• tooltip

SensitivityLabelDetailsCollection

Properties:

• items

Methods:

• getCount(...)
• getItem(...)
• getItemAt(...)
• getItemOrNullObject(...)

Chart

Properties:

• axes
• chartType
• dataLabels
• dataSourceKind
• displayBlanksAs
• format
• height
• id
• left
• legend
• name
• plotArea
• plotVisibleOnly
• series
• showDataLabelsOverMaximum
• style
• title
• top
• width

Methods:

• delete(...)
• setData(...)
• setDataRange(...)

ChartAxes

Properties:

• categoryAxis
• valueAxis

Methods:

• getItem(...)

ChartAxis

Properties:

• axisGroup
• baseTimeUnit
• categoryType
• linkNumberFormat
• majorGridlines
• majorTimeUnitScale
• majorUnit
• maximum
• minimum
• minorGridlines
• minorTimeUnitScale
• minorUnit
• numberFormat
• reversePlotOrder
• title
• type
• visible

ChartGridlines

Properties:

• visible

ChartAxisTitle

Properties:

• text
• visible

ChartTitle

Properties:

• overlay
• text
• visible

ChartLegend

Properties:

• overlay
• position
• visible

ChartSeriesCollection

Properties:

• count
• items

Methods:

• getCount(...)
• getItemAt(...)

ChartSeries

Properties:

• axisGroup
• binOptions
• boxwhiskerOptions
• bubbleScale
• chartType
• dataLabels
• doughnutHoleSize
• firstSliceAngle
• format
• gapWidth
• hasDataLabels
• invertIfNegative
• markerBackgroundColor
• markerForegroundColor
• markerSize
• markerStyle
• name
• overlap
• showConnectorLines
• smooth
• varyByCategories

Methods:

• delete(...)
• getDimensionDataSourceString(...)
• getDimensionDataSourceType(...)
• setBubbleSizes(...)
• setValues(...)
• setXAxisValues(...)

ChartBinOptions

Properties:

• allowOverflow
• allowUnderflow
• count
• overflowValue
• type
• underflowValue
• width

ChartBoxwhiskerOptions

Properties:

• quartileCalculation
• showInnerPoints
• showMeanLine
• showMeanMarker
• showOutlierPoints

ChartDataLabels

Properties:

• format
• linkNumberFormat
• numberFormat
• position
• separator
• showBubbleSize
• showCategoryName
• showLeaderLines
• showLegendKey
• showPercentage
• showSeriesName
• showValue

ChartDataLabelFormat

Properties:

• border
• fill
• font

ChartAreaFormat

Properties:

• border
• fill
• font
• roundedCorners

ChartPlotArea

Properties:

• format

ChartPlotAreaFormat

Properties:

• border
• fill

ChartSeriesFormat

Properties:

• fill
• line

ChartFill

Methods:

• clear(...)
• getSolidColor(...)
• setSolidColor(...)

ChartLineFormat

Properties:

• color
• lineStyle
• weight

Methods:

• clear(...)

ChartBorder

Properties:

• color
• lineStyle
• weight

Methods:

• clear(...)

ChartFont

Properties:

• bold
• color
• italic
• name
• size
• underline