@shbernal/ts-pptx / index / ObjectOptions

Interface: ObjectOptions

Defined in: src/types/slide.ts:57

Reusable optional data/path fields. Use DataOrPathRequiredProps for APIs that require at least one source.

Extends

ImageBaseProps.PositionProps.ShapeProps.TableCellProps.TextPropsOptions

Properties

_bodyProp?

optional _bodyProp?: object

Defined in: src/types/text.ts:337

align?

optional align?: AlignH

anchor?

optional anchor?: TextAnchor

bIns?

optional bIns?: number

lIns?

optional lIns?: number

numCol?

optional numCol?: number

prstTxWarp?

optional prstTxWarp?: string

rIns?

optional rIns?: number

spcCol?

optional spcCol?: number

tIns?

optional tIns?: number

vert?

optional vert?: "horz" | "vert" | "vert270" | "wordArtVert" | "eaVert" | "mongolianVert" | "wordArtVertRtl"

wrap?

optional wrap?: boolean

Inherited from

TextPropsOptions._bodyProp

_connectorAdj?

optional _connectorAdj?: number[]

Defined in: src/types/slide.ts:61

Connector adjust-guide values (OOXML 1000ths-of-a-percent), one per bend; emitted as <a:gd name="adjN">

_endCxn?

optional _endCxn?: object

Defined in: src/types/slide.ts:65

Connector end-point binding: target shape objectName (raw, as the caller spelled it) + connection-site index; resolved to <a:endCxn> at serialize time

idx

idx: number

name

name: string

_lineIdx?

optional _lineIdx?: number

Defined in: src/types/text.ts:351

Inherited from

TextPropsOptions._lineIdx

_placeholderIdx?

optional _placeholderIdx?: number

Defined in: src/types/slide.ts:58

_placeholderType?

optional _placeholderType?: "media" | "body" | "title" | "chart" | "pic" | "tbl"

Defined in: src/types/slide.ts:59

_startCxn?

optional _startCxn?: object

Defined in: src/types/slide.ts:63

Connector start-point binding: target shape objectName (raw, as the caller spelled it) + connection-site index; resolved to <a:stCxn> at serialize time

idx

idx: number

name

name: string

_szAuto?

optional _szAuto?: object

Defined in: src/types/slide.ts:73

Image: which dimensions were omitted by the user and should be derived from the image's natural pixel size at serialize time. Path-based images can't be measured synchronously in addImage() (bytes are loaded async during export), so the missing extent is backfilled once _relsMedia[].data is populated. { w, h } true means "derive this side from the natural ratio". Base64 data images are measured eagerly in addImage() and never set this.

h

h: boolean

w

w: boolean

adjustHandles?

optional adjustHandles?: ShapeAdjustHandle[]

Defined in: src/types/shape.ts:170

Adjust handles (<a:ahLst>) for a custGeom shape — draggable handles (XY or polar), optionally bound to guides via gdRef*.

Inherited from

ShapeProps.adjustHandles

align?

optional align?: HAlign

Defined in: src/types/shape.ts:89

Horizontal alignment

Default

'left'

Inherited from

ShapeProps.align

altText?

optional altText?: string

Defined in: src/types/media.ts:34

Alt Text value ("How would you describe this object and its contents to someone who is blind?")

PowerPoint: [right-click on an image] > "Edit Alt Text..."

Inherited from

ImageBaseProps.altText

anchorCtr?

optional anchorCtr?: boolean

Defined in: src/types/table.ts:225

Centre the cell's whole text block horizontally within the cell (a:tcPr/@anchorCtr), independent of each paragraph's own align.

The two do different things and compose: align decides where each line sits inside the text block, anchorCtr decides where that block sits inside the cell. With left-aligned text in a wide cell, anchorCtr: true centres the ragged-right column of lines as a unit while keeping their left edges flush with each other.

false is the schema default, so it emits nothing — the same reasoning as horzOverflow: 'clip'.

Default

false

Inherited from

TableCellProps.anchorCtr

angleRange?

optional angleRange?: [number, number]

Defined in: src/types/shape.ts:96

Radius (only for ShapeType.pie, ShapeType.arc, ShapeType.blockArc)

In the case of ShapeType.blockArc you have to setup the arcThicknessRatio
values: [0-359, 0-359]

Default

[270, 0]

Inherited from

ShapeProps.angleRange

arcThicknessRatio?

optional arcThicknessRatio?: number

Defined in: src/types/shape.ts:115

Radius (only for ShapeType.blockArc)

You have to setup the angleRange values too
values: 0.0-1.0

Default

0.5

Inherited from

ShapeProps.arcThicknessRatio

autoPageCharWeight?

optional autoPageCharWeight?: number

Defined in: src/types/table.ts:184

Auto-paging character weight

adjusts how many characters are used before lines wrap
range: -1.0 to 1.0

Default

0.0

Example

0.5 // lines are longer (increases the number of characters that can fit on a given line)

Inherited from

TableCellProps.autoPageCharWeight

autoPageLineWeight?

optional autoPageLineWeight?: number

Defined in: src/types/table.ts:192

Auto-paging line weight

adjusts how many lines are used before slides wrap
range: -1.0 to 1.0

Default

0.0

Example

0.5 // tables are taller (increases the number of lines that can fit on a given slide)

Inherited from

TableCellProps.autoPageLineWeight

baseline?

optional baseline?: number

Defined in: src/types/text.ts:353

Inherited from

TextPropsOptions.baseline

biLevel?

optional biLevel?: object

Defined in: src/types/media.ts:224

Recolor the image to two-level black & white (<a:biLevel thresh="…"/>)

every pixel at/above the luminance threshold becomes white, everything below it black (MS-PPT > Format Picture > Picture Color > Recolor > Black and White …%)

threshold

threshold: number

Luminance split point as a 0.0–1.0 fraction (serialized to thresh, the 0–1 fraction ×100000).

Example

{ threshold: 0.5 } // split at 50% luminance

Inherited from

ImageBaseProps.biLevel

bold?

optional bold?: boolean

Defined in: src/types/text.ts:23

Bold style

Default

false

Inherited from

TableCellProps.bold

border?

optional border?: BorderProps | [BorderProps, BorderProps, BorderProps, BorderProps]

Defined in: src/types/table.ts:202

The cell's four edge borders (a:tcPr/a:lnT|lnR|lnB|lnL).

a single BorderProps is broadcast to all four sides
an array is read in TRBL order ([top, right, bottom, left])

Overrides the table-level TableProps.border default entirely — the two do not merge per side. For the two corner-to-corner rules see diagonal; for the table's outside edge see TableProps.outerBorder.

Inherited from

TableCellProps.border

breakLine?

optional breakLine?: boolean

Defined in: src/types/text.ts:28

Add a line-break

Default

false

Inherited from

TableCellProps.breakLine

bullet?

optional bullet?: boolean | "inherit" | { characterCode?: string; color?: string; fontFace?: string; image?: { data?: string; path?: string; }; indent?: number; numberStartAt?: number; numberType?: "alphaLcParenBoth" | "alphaLcParenR" | "alphaLcPeriod" | "alphaUcParenBoth" | "alphaUcParenR" | "alphaUcPeriod" | "arabicParenBoth" | "arabicParenR" | "arabicPeriod" | "arabicPlain" | "romanLcParenBoth" | "romanLcParenR" | "romanLcPeriod" | "romanUcParenBoth" | "romanUcParenR" | "romanUcPeriod"; size?: number; type?: "number" | "bullet"; }

Defined in: src/types/text.ts:53

Add standard or custom bullet

use true for standard bullet
pass object options for custom bullet
false (and omitting the option) is the explicit off: it writes <a:buNone/> plus marL="0" indent="0", which overrides whatever bullet the layout's or master's list style sets for this level
'inherit' states nothing at all — no bullet child and no margin attributes — so the list style keeps reaching the paragraph. This is the one state omission cannot spell, because omitting the option means false here for compatibility

The margins are only a default of the bullet state: paraMarginLeft and paraIndent state @marL/@indent independently in any of the three, including an inherited margin under a drawn bullet.

Union Members

boolean

"inherit"

Type Literal

{ characterCode?: string; color?: string; fontFace?: string; image?: { data?: string; path?: string; }; indent?: number; numberStartAt?: number; numberType?: "alphaLcParenBoth" | "alphaLcParenR" | "alphaLcPeriod" | "alphaUcParenBoth" | "alphaUcParenR" | "alphaUcPeriod" | "arabicParenBoth" | "arabicParenR" | "arabicPeriod" | "arabicPlain" | "romanLcParenBoth" | "romanLcParenR" | "romanLcPeriod" | "romanUcParenBoth" | "romanUcParenR" | "romanUcPeriod"; size?: number; type?: "number" | "bullet"; }

characterCode?

optional characterCode?: string

Bullet character code (unicode)

Example

'25BA' // 'BLACK RIGHT-POINTING POINTER' (U+25BA)

color?

optional color?: string

Bullet glyph color (separate from the text run color)

Example

'FF0000' // red bullet

fontFace?

optional fontFace?: string

Bullet glyph font typeface (<a:buFont/>), e.g. for symbol-font bullets

Example

'Wingdings' // render `characterCode` using the Wingdings font

image?

optional image?: object

Image to use as the bullet glyph ("picture bullet", <a:buBlip>)

supply an image path (filesystem/URL) or base64 data (same forms as addImage())
raster formats (PNG/JPG/GIF) and SVG are supported; use size to scale relative to the text height
SVG bullets embed a PNG preview plus the SVG (the same dual-rel handling as addImage())
takes precedence over type/characterCode when set

Examples

image: { path: 'images/star.png' }

image: { data: 'image/png;base64,iVBOR...' }

image: { path: 'images/star.svg' }

image.data?

optional data?: string

image.path?

optional path?: string

indent?

optional indent?: number

Indentation (space between bullet and text) (points)

Default

27 // DEF_BULLET_MARGIN

Example

10 // Indents text 10 points from bullet

numberStartAt?

optional numberStartAt?: number

Number bullets start at

Default

Example

10 // numbered bullets start with 10

numberType?

optional numberType?: "alphaLcParenBoth" | "alphaLcParenR" | "alphaLcPeriod" | "alphaUcParenBoth" | "alphaUcParenR" | "alphaUcPeriod" | "arabicParenBoth" | "arabicParenR" | "arabicPeriod" | "arabicPlain" | "romanLcParenBoth" | "romanLcParenR" | "romanLcPeriod" | "romanUcParenBoth" | "romanUcParenR" | "romanUcPeriod"

Number type

Example

'romanLcParenR' // roman numerals lower-case with paranthesis right

size?

optional size?: number

Bullet glyph size as a percentage of the run's text size (25–400)

Default

Example

80 // bullet glyph is 80% of the text size

type?

optional type?: "number" | "bullet"

Bullet type

Default

bullet

Default

false

Inherited from

TableCellProps.bullet

caps?

optional caps?: "small" | "all" | "none"

Defined in: src/types/text.ts:149

Text capitalization (a:rPr/@cap, ST_TextCapsType)

'all' = ALL CAPS
'small' = Small Caps
'none' = the explicit off: it writes cap="none", which overrides a capitalization the run would otherwise inherit. Omitting the option states nothing and lets that inheritance stand
PowerPoint: Font > Effects > All Caps / Small Caps

Default

(unset) inherit

Inherited from

TableCellProps.caps

cell3D?

optional cell3D?: TableCell3DProps

Defined in: src/types/table.ts:231

A 3-D bevel on the cell (a:tcPr/a:cell3D). Niche: PowerPoint's table UI has no control for it, so it reaches a deck from a theme or another producer, and this exists to author and reproduce one. See TableCell3DProps.

Inherited from

TableCellProps.cell3D

charSpacing?

optional charSpacing?: number

Defined in: src/types/text.ts:357

Character spacing

Inherited from

TextPropsOptions.charSpacing

clrChange?

optional clrChange?: object

Defined in: src/types/media.ts:235

Recolor the image by mapping one source color to another (<a:clrChange>)

every pixel matching from is repainted to — the classic "swap the flat background out" recolour (MS-PPT > Format Picture > Picture Color > Set Transparent Color is the single-colour sibling)
colors accept HexColor or ThemeColor, same as fills / duotone

from

from: string

Source color to replace (<a:clrFrom>).

to

to: string

Replacement color (<a:clrTo>).

Example

{ from: '000000', to: 'FF0000' } // turn black pixels red

Inherited from

ImageBaseProps.clrChange

color?

optional color?: string

Defined in: src/types/text.ts:157

Text color

HexColor or ThemeColor
MS-PPT > Format Shape > Text Options > Text Fill & Outline > Text Fill > Color

Examples

'FF0000' // hex color (red)

SchemeColor.text1 // Theme color (Text1)

Inherited from

TableCellProps.color

colspan?

optional colspan?: number

Defined in: src/types/table.ts:235

Cell colspan

Inherited from

TableCellProps.colspan

columns?

optional columns?: number

Defined in: src/types/text.ts:365

Number of text columns in the text body

PowerPoint: Format Shape > Shape Options > Size & Properties > Text Box > Columns > "Number"
range: 1-16

Default

Example

2 // flow text into two columns

Inherited from

TextPropsOptions.columns

columnSpacing?

optional columnSpacing?: number

Defined in: src/types/text.ts:373

Spacing between text columns (points)

PowerPoint: Format Shape > Shape Options > Size & Properties > Text Box > Columns > "Spacing"
only applies when columns > 1

Default

Example

10 // 10pt gap between columns

Inherited from

TextPropsOptions.columnSpacing

colW?

optional colW?: number | number[]

Defined in: src/types/slide.ts:78

connectionSites?

optional connectionSites?: ShapeConnectionSite[]

Defined in: src/types/shape.ts:165

Connection sites (<a:cxnLst>) for a custGeom shape — the points a connector can attach to. Positions are absolute in the object's own space (like points); a startShapeIdx/endShapeIdx on an addConnector indexes into this list.

Example

[{ ang: 0, x: 1, y: 0 }, { ang: 180, x: 0, y: 1 }]

Inherited from

ShapeProps.connectionSites

crop?

optional crop?: object

Defined in: src/types/media.ts:125

Crop the source image to a sub-region by percentage edge insets, emitted verbatim as OOXML <a:srcRect>.

each value is the percent (0–100) trimmed off that edge of the source image, the same model PowerPoint's Picture Format > Crop uses; l+r and t+b must each be < 100
the remaining sub-region is stretched to fill the picture's displayed w×h box, so this is the faithful way to reproduce a deck that maps several icons out of one composite raster
operates on the source image directly (independent of natural-pixel measurement), so unlike sizing: 'crop' (which crops in displayed inches) it works for SVG and unmeasurable formats
mutually exclusive with sizing; if both are set crop wins and sizing is ignored

b?

optional b?: number

Percent (0–100) trimmed from the bottom edge of the source image.

Default

l?

optional l?: number

Percent (0–100) trimmed from the left edge of the source image.

Default

r?

optional r?: number

Percent (0–100) trimmed from the right edge of the source image.

Default

t?

optional t?: number

Percent (0–100) trimmed from the top edge of the source image.

Default

Example

{ l: 0, t: 0, r: 50, b: 50 } // keep the top-left quadrant of the source image

Inherited from

ImageBaseProps.crop

cx?

optional cx?: Coord

Defined in: src/types/slide.ts:75

cy?

optional cy?: Coord

Defined in: src/types/slide.ts:76

data?

optional data?: string

Defined in: src/types/core.ts:76

base64-encoded string

Useful for avoiding potential path/server issues

Example

'image/png;base64,iVtDafDrBF[...]=' // pre-encoded image in base-64

Inherited from

TextPropsOptions.data

diagonal?

optional diagonal?: TableCellDiagonals

Defined in: src/types/table.ts:211

The cell's corner-to-corner rules — PowerPoint's "Diagonal Down/Up Border".

Kept off border's tuple on purpose: see TableCellDiagonals. A diagonal on a merged cell is one stroke across the whole region, so only the span origin carries it — the covered cells inherit the origin's edges but never its diagonals.

Example

diagonal: { tlToBr: { type:'solid', color:'C00000' } } // strike the cell out

Inherited from

TableCellProps.diagonal

duotone?

optional duotone?: object

Defined in: src/types/media.ts:202

Recolor the image as a two-tone (duotone) effect

maps the image's shadows to shadow and its highlights to highlight
serializes <a:duotone> inside the picture's <a:blip> (MS-PPT > Format Picture > Picture Color > Recolor)
colors accept HexColor or ThemeColor, same as fills
the classic brand treatment: tint stock photography into a single brand hue

highlight

highlight: string

Color mapped to the image's light/highlight tones.

shadow

shadow: string

Color mapped to the image's dark/shadow tones.

Example

{ shadow: '250F6B', highlight: 'FFFFFF' } // deep-blue duotone

Inherited from

ImageBaseProps.duotone

fill?

optional fill?: ShapeFillProps

Defined in: src/types/shape.ts:122

Shape fill color properties

Examples

{ color:'FF0000' } // hex color (red)

{ color:'0088CC', transparency:50 } // hex color, 50% transparent

{ color:SchemeColor.accent1 } // Theme color Accent1

Inherited from

ShapeProps.fill

fit?

optional fit?: "resize" | "none" | TextFitShrinkProps | "shrink"

Defined in: src/types/table.ts:293

Shrink cell text to fit when it would overflow the cell's fixed height.

'shrink' measures the wrapped text and bakes a reduced literal font size onto the cell's runs so the text fits — PowerPoint does not support text autofit (normAutofit) inside table cells, so there is no font-scale flag to set; the size itself is lowered, which both PowerPoint and LibreOffice render identically with no edit/resize.
Requires the cell font registered via TsPptx.registerFontMetrics; without metrics it is a no-op (the cell keeps its authored size) and warns once.
Only triggers when the cell's row has a fixed height that the text exceeds. With auto-height rows (no rowH/h), the row simply grows, so nothing shrinks.
Only 'shrink' is acted on for cells. 'resize' and the object form are ignored here: a table row already auto-grows to fit its tallest cell (the cell equivalent of spAutoFit), so there is nothing to bake. (The wider union is shared with TextPropsOptions.fit so table-level fit can cascade to cells.)

Example

'shrink' // measured when the cell font is registered; else no-op

Inherited from

TableCellProps.fit

flipH?

optional flipH?: boolean

Defined in: src/types/media.ts:39

Flip horizontally?

Default

false

Inherited from

ImageBaseProps.flipH

flipV?

optional flipV?: boolean

Defined in: src/types/media.ts:44

Flip vertical?

Default

false

Inherited from

ImageBaseProps.flipV

fontFace?

optional fontFace?: string

Defined in: src/types/text.ts:167

Font face name

Applied to the Latin (<a:latin>) and complex-script (<a:cs>) font slots, matching how PowerPoint writes a font picked from the UI. The East Asian slot (<a:ea>) is left to inherit from the theme unless fontFaceEA is set — forcing a Latin-only face into the East Asian slot duplicates/ghosts text in Office 365.

Example

'Arial' // Arial font

Inherited from

TableCellProps.fontFace

fontFaceEA?

optional fontFaceEA?: string

Defined in: src/types/text.ts:175

East Asian font face name (<a:ea> slot), used to render CJK (Chinese/Japanese/Korean) glyphs

Set this when the East Asian font differs from fontFace. When omitted, <a:ea> inherits the theme East Asian font, which is what PowerPoint does for Latin fonts.

Example

'微軟正黑體' // render East Asian glyphs with Microsoft JhengHei

Inherited from

TableCellProps.fontFaceEA

fontSize?

optional fontSize?: number

Defined in: src/types/text.ts:180

Font size

Example

12 // Font size 12

Inherited from

TableCellProps.fontSize

glow?

optional glow?: TextGlowProps

Defined in: src/types/text.ts:420

Inherited from

TextPropsOptions.glow

grayscale?

optional grayscale?: boolean

Defined in: src/types/media.ts:217

Recolor the image to grayscale (<a:grayscl/>)

maps every pixel to its luminance grey (MS-PPT > Format Picture > Picture Color > Recolor > Grayscale)
the cheapest recolour: no payload
mutually exclusive with the other recolour modes (duotone/biLevel/clrChange); if several are set, the first present in document order wins on read-back

Default

false

Example

true // desaturate the image

Inherited from

ImageBaseProps.grayscale

guides?

optional guides?: ShapeGuide[]

Defined in: src/types/shape.ts:158

Geometry guides (<a:gdLst>) for a custGeom shape — named construction formulas that connection sites / adjust handles can reference. Advanced: each formula is emitted verbatim.

Example

[{ name: 'w2', formula: 'val 10800' }]

Inherited from

ShapeProps.guides

h?

optional h?: Coord

Defined in: src/types/core.ts:49

Height

inches or percentage

Examples

10.25 // height in inches

'75%' // height as percentage of slide size

Inherited from

ImageBaseProps.h

hasBandedColumns?

optional hasBandedColumns?: boolean

Defined in: src/types/slide.ts:83

hasBandedRows?

optional hasBandedRows?: boolean

Defined in: src/types/slide.ts:82

hasFirstColumn?

optional hasFirstColumn?: boolean

Defined in: src/types/slide.ts:84

hasFooter?

optional hasFooter?: boolean

Defined in: src/types/slide.ts:81

hasHeader?

optional hasHeader?: boolean

Defined in: src/types/slide.ts:80

hasLastColumn?

optional hasLastColumn?: boolean

Defined in: src/types/slide.ts:85

highlight?

optional highlight?: string

Defined in: src/types/text.ts:185

Text highlight color (hex format)

Example

'FFFF00' // yellow

Inherited from

TableCellProps.highlight

horzOverflow?

optional horzOverflow?: "clip" | "overflow"

Defined in: src/types/table.ts:265

What happens to a single glyph wider than the cell's text width (a:tcPr/@horzOverflow).

'clip' (PowerPoint's default) cuts the glyph off at the cell edge
'overflow' lets it draw past the edge, over whatever is beside it

This is not a text-wrap switch, despite the name. Lines always wrap to the column width; only an individual character too wide to fit on a line by itself is affected, so it matters for oversized display type, wide CJK/emoji glyphs, and icon fonts in a narrow column. PowerPoint has no per-cell no-wrap at all — wrap="none" on a cell's a:bodyPr is discarded on the next save (probe: test/read/fixtures/authoring/probe-table-cell-wrap.ps1). 'clip' is written as asked but is the schema default, so PowerPoint drops the attribute again the first time it saves the deck — the visible result is the same either way, and leaving this unset emits nothing at all.

Default

(unset — PowerPoint clips)

Example

'overflow' // a 60pt glyph in a 0.5in column draws whole instead of being cut

Inherited from

TableCellProps.horzOverflow

hyperlink?

optional hyperlink?: HyperlinkProps

Defined in: src/types/media.ts:45

Add hyperlink to shape

Example

hyperlink: { url: "https://example.com", tooltip: "Visit Homepage" },

Inherited from

ImageBaseProps.hyperlink

indentLevel?

optional indentLevel?: number

Defined in: src/types/text.ts:422

Inherited from

TextPropsOptions.indentLevel

isTextBox?

optional isTextBox?: boolean

Defined in: src/types/text.ts:423

Inherited from

TextPropsOptions.isTextBox

italic?

optional italic?: boolean

Defined in: src/types/text.ts:190

italic style

Default

false

Inherited from

TableCellProps.italic

lang?

optional lang?: string

Defined in: src/types/text.ts:197

language

ISO 639-1 standard language code

Default

'en-US' // english US

Example

'fr-CA' // french Canadian

Inherited from

TableCellProps.lang

line?

optional line?: ShapeLineProps

Defined in: src/types/media.ts:53

Border line (<a:ln> outline) drawn around the image

same options as a shape outline; a picture supports a single outline, not per-side borders
MS-PPT: Format Picture > Line

Examples

{ color: '0088CC', width: 2 }                   // 2pt blue border

{ color: '666666', width: 1, dashType: 'dash' } // dashed gray border

Inherited from

ImageBaseProps.line

lineSpacing?

optional lineSpacing?: number

Defined in: src/types/text.ts:430

Line spacing (pt)

PowerPoint: Paragraph > Indents and Spacing > Line Spacing: > "Exactly"

Example

28 // 28pt

Inherited from

TextPropsOptions.lineSpacing

lineSpacingMultiple?

optional lineSpacingMultiple?: number

Defined in: src/types/text.ts:437

line spacing multiple (percent)

range: 0.0-9.99
PowerPoint: Paragraph > Indents and Spacing > Line Spacing: > "Multiple"

Example

1.5 // 1.5X line spacing

Inherited from

TextPropsOptions.lineSpacingMultiple

margin?

optional margin?: Margin

Defined in: src/types/slide.ts:77

Cell margin (inches)

Default

Overrides

TableCellProps.margin

objectLock?

optional objectLock?: ObjectLockProps

Defined in: src/types/object.ts:54

Object lock flags (DrawingML a:spLocks / a:picLocks / a:graphicFrameLocks)

restrict how the object can be manipulated in PowerPoint (e.g. prevent moving, resizing, or grouping)
each flag maps 1:1 to the OOXML attribute of the same name; only flags set to true are emitted
PowerPoint UI: Selection Pane / right-click protections (most locks are honored at edit time, not as a password)
flags only apply to the object types that support them (see each flag); flags set on an unsupported object type are ignored with a console warning

Examples

{ noMove: true, noResize: true } // pin an object in place

{ noGrp: true } // exclude from grouping

Inherited from

ImageBaseProps.objectLock

objectName?

optional objectName?: string

Defined in: src/types/object.ts:36

Object name

used instead of default "Object N" name
PowerPoint: Home > Arrange > Selection Pane...

Default

'Object 1'

Example

'Antenna Design 9'

Inherited from

ImageBaseProps.objectName

outerBorder?

optional outerBorder?: BorderProps | [BorderProps?, BorderProps?, BorderProps?, BorderProps?]

Defined in: src/types/slide.ts:93

Table perimeter border. addTableDefinition normalizes it to a 4-tuple (TRBL, sides left unset as undefined) before it reaches the emitter, so the serializer never has to re-handle the single-BorderProps form.

outline?

optional outline?: object

Defined in: src/types/text.ts:449

color

color: string

size

size: number

Inherited from

TextPropsOptions.outline

paraIndent?

optional paraIndent?: number | "inherit"

Defined in: src/types/text.ts:214

First-line indent (points) — a:pPr/@indent, the offset of the paragraph's FIRST line from paraMarginLeft. Negative hangs the first line to the left of the body, which is what a bulleted paragraph does; positive indents it to the right, the "first line indented" prose form. PowerPoint: Paragraph > Indentation > Special.

'inherit' writes no @indent at all, so the paragraph takes whatever its list style (a:lstStyle → placeholder → layout → master) sets — the same third state bullet spells, on the attribute beside it
omitting the option keeps the bullet-derived default: a drawn bullet hangs the first line by its margin, bullet: false writes indent="0", bullet: 'inherit' writes nothing
a value here overrides all of those, in every bullet state

Examples

-18 // hang the first line 18pt left of the body text

18 // indent the first line 18pt, prose style

'inherit' // keep the list style's indent, even on a bulleted paragraph

Inherited from

TableCellProps.paraIndent

paraMarginLeft?

optional paraMarginLeft?: number | "inherit"

Defined in: src/types/text.ts:229

Left margin of the paragraph (points) — a:pPr/@marL, where the paragraph's body text starts. This is the paragraph's own margin, not the text frame's internal padding (margin) and not the discrete outline level (indentLevel, which writes a:p/@lvl). PowerPoint: Paragraph > Indentation > Before text.

'inherit' writes no @marL at all, so the paragraph takes whatever its list style (a:lstStyle → placeholder → layout → master) sets — the third state that omission cannot spell, since omitting it writes the bullet-derived default
omitting the option keeps that default: a drawn bullet writes its own margin (see bullet.indent), bullet: false writes marL="0", bullet: 'inherit' writes nothing
a value here overrides all of those, in every bullet state

Examples

36 // body text starts 36pt (0.5in) from the frame's text edge

'inherit' // keep the list style's margin, even on a bulleted paragraph

Inherited from

TableCellProps.paraMarginLeft

paraSpaceAfter?

optional paraSpaceAfter?: number

Defined in: src/types/text.ts:450

Inherited from

TextPropsOptions.paraSpaceAfter

paraSpaceBefore?

optional paraSpaceBefore?: number

Defined in: src/types/text.ts:451

Inherited from

TextPropsOptions.paraSpaceBefore

path?

optional path?: string

Defined in: src/types/core.ts:69

URL or relative path

Example

'https://onedrives.com/myimg.png` // retrieve image via URL
@example '/home/user/images/myimg.png` // retrieve image via local path

Inherited from

TextPropsOptions.path

placeholder?

optional placeholder?: string

Defined in: src/types/media.ts:62

Name of a picture placeholder defined on the slide layout/master to populate

when it matches a layout/master placeholder, the image inherits that placeholder's position and size for any of x/y/w/h not supplied explicitly; explicit values always win

Example

'picph'

See

https://docs.microsoft.com/en-us/office/vba/api/powerpoint.ppplaceholdertype

Inherited from

ImageBaseProps.placeholder

points?

optional points?: GeometryPoint[]

Defined in: src/types/media.ts:92

Clip the image to an arbitrary freeform path (custGeom)

takes precedence over shape / rounding when present
coordinates are authored in the image's own inch/EMU space (0..w, 0..h), not slide-relative and not normalized
supports the same path DSL as freeform shapes: moveTo / lnTo / cubicBezTo / quadBezTo / arcTo / close

Example

[{ x: 1, y: 0 }, { x: 2, y: 2 }, { x: 0, y: 2 }, { close: true }] // triangular photo clip

Inherited from

ImageBaseProps.points

rectRadius?

optional rectRadius?: number

Defined in: src/types/media.ts:98

Rounded rectangle corner radius (inches) when shape: 'roundRect'

values: 0.0 to 1.0

Default

Inherited from

ImageBaseProps.rectRadius

rotate?

optional rotate?: number

Defined in: src/types/media.ts:69

Image rotation (degrees)

range: -360 to 360

Default

Example

180 // rotate image 180 degrees

Inherited from

ImageBaseProps.rotate

rounding?

optional rounding?: boolean

Defined in: src/types/media.ts:75

Enable image rounding (clips the image to a circle/ellipse)

shorthand for shape: 'ellipse'; shape takes precedence when both are set

Default

false

Inherited from

ImageBaseProps.rounding

rowH?

optional rowH?: number | number[]

Defined in: src/types/slide.ts:79

rowspan?

optional rowspan?: number

Defined in: src/types/table.ts:275

Cell rowspan

Inherited from

TableCellProps.rowspan

rtl?

optional rtl?: boolean

Defined in: src/types/slide.ts:86

rtlMode?

optional rtlMode?: boolean

Defined in: src/types/text.ts:481

Whether to enable right-to-left mode

Default

false

Inherited from

TextPropsOptions.rtlMode

shadow?

optional shadow?: ShadowProps

Defined in: src/types/media.ts:112

Shadow Props

MS-PPT > Format Picture > Shadow

Example

{ type: 'outer', color: '000000', transparency: 50, blur: 20,  offset: 20, angle: 270 }

Inherited from

ImageBaseProps.shadow

shape?

optional shape?: SHAPE_NAME

Defined in: src/types/media.ts:84

Clip the image to a preset shape geometry ("fit image into shape")

accepts any PowerPoint preset geometry name, e.g. 'roundRect', 'hexagon', 'ellipse'
combine with sizing: { type: 'cover', ... } for an aspect-correct fill of the shape box
use rectRadius to set the corner radius for 'roundRect'

Examples

'roundRect' // rounded-rectangle avatar

'hexagon'   // hexagonal photo

Inherited from

ImageBaseProps.shape

shapeAdjust?

optional shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[]

Defined in: src/types/media.ts:105

Preset-geometry adjustment handles (<a:avLst> guides) for the clip shape.

tune adjustment handles that lack a dedicated option, e.g. chevron point depth
accepts a single guide or an array; each value is a 0.0–1.0 fraction (see ShapeAdjustValue)

Example

{ name: 'adj', value: 0.25 }

Inherited from

ImageBaseProps.shapeAdjust

sizing?

optional sizing?: object

Defined in: src/types/media.ts:140

Image sizing options

omit entirely for the default: a raster fills the w×h box, a vector (SVG) source is letterboxed to its own aspect ratio inside that box

h?

optional h?: Coord

Image height

inches or percentage
defaults to the picture's own h

Examples

10.25 // position in inches

'75%' // position as percentage of slide size

type

type: "contain" | "crop" | "cover" | "stretch"

Sizing type

cover / contain fit the image into the w×h box using the image's natural aspect ratio — read from the embedded PNG/JPEG/GIF/BMP/WebP header, or from an SVG's width/height or viewBox. If the natural size cannot be determined (an unrecognized format, or an SVG carrying neither) the displayed w/h ratio is used as a fallback and a warning is logged.
crop cuts a window out of the displayed image using the x/y/w/h offsets.
stretch fills the box regardless of aspect ratio. This is what a raster does anyway; name it explicitly to opt a vector source out of its aspect-correct default.

w?

optional w?: Coord

Image width

inches or percentage
defaults to the picture's own w, which is what cover/contain almost always want

Examples

10.25 // position in inches

'75%' // position as percentage of slide size

x?

optional x?: Coord

Offset from left to crop image

crop only
inches or percentage

Examples

10.25 // position in inches

'75%' // position as percentage of slide size

y?

optional y?: Coord

Offset from top to crop image

crop only
inches or percentage

Examples

10.25 // position in inches

'75%' // position as percentage of slide size

Inherited from

ImageBaseProps.sizing

softBreakBefore?

optional softBreakBefore?: boolean

Defined in: src/types/text.ts:234

Add a soft line-break (shift+enter) before line text content

Default

false

Inherited from

TableCellProps.softBreakBefore

strike?

optional strike?: boolean | "noStrike" | "sngStrike" | "dblStrike"

Defined in: src/types/text.ts:496

Strikethrough (a:rPr/@strike, ST_TextStrikeType — ECMA-376 §20.1.10.78)

true is 'sngStrike'; 'dblStrike' is the double rule
'noStrike' is the explicit off: it writes strike="noStrike", which overrides a strikethrough the run would otherwise inherit from its list style, placeholder, layout or master
false, like leaving the option out, writes no attribute at all and so states nothing — the run keeps whatever it inherits. This matches bold/italic, whose falsy arm is likewise an omission; reach for 'noStrike' when the intent is "not struck" rather than "unspecified"

Default

(unset) inherit

Inherited from

TextPropsOptions.strike

subscript?

optional subscript?: boolean

Defined in: src/types/text.ts:497

Inherited from

TextPropsOptions.subscript

superscript?

optional superscript?: boolean

Defined in: src/types/text.ts:498

Inherited from

TextPropsOptions.superscript

svg?

optional svg?: string

Defined in: src/types/media.ts:247

Raw SVG markup to embed as the image source

convenience for data: 'data:image/svg+xml;base64,...'; ts-pptx encodes it for you
ignored when data or path is also provided

Example

'<svg viewBox="0 0 24 24">...</svg>'

Inherited from

ImageBaseProps.svg

tableFill?

optional tableFill?: ShapeFillProps

Defined in: src/types/slide.ts:95

Table background (a:tblPr fill), as distinct from fill, which is stamped onto each cell.

tableStyle?

optional tableStyle?: TableStyle

Defined in: src/types/slide.ts:87

tabStops?

optional tabStops?: object[]

Defined in: src/types/text.ts:240

tab stops

PowerPoint: Paragraph > Tabs > Tab stop position

alignment?

optional alignment?: "r" | "ctr" | "l" | "dec"

position

position: number

Example

[{ position:1 }, { position:3 }] // Set first tab stop to 1 inch, set second tab stop to 3 inches

Inherited from

TableCellProps.tabStops

textDirection?

optional textDirection?: "horz" | "vert" | "vert270" | "wordArtVert"

Defined in: src/types/text.ts:249

text direction horz = horizontal vert = rotate 90^ vert270 = rotate 270^ wordArtVert = stacked

Default

'horz'

Inherited from

TableCellProps.textDirection

textWarp?

optional textWarp?: string

Defined in: src/types/text.ts:36

Preset text warp / WordArt shape (<a:bodyPr><a:prstTxWarp prst="..">), which bends the text along a preset path (arch, circle, wave, …). The value is an OOXML ST_TextShapeType preset name.

Examples

'textArchUp' // bend text along an upward arch (e.g. a label following a ring/arc)

'textCircle'

Inherited from

TableCellProps.textWarp

transparency?

optional transparency?: number

Defined in: src/types/media.ts:193

Transparency (percent)

MS-PPT > Format Picture > Picture > Picture Transparency > Transparency
range: 0-100

Default

Example

25 // 25% transparent

Inherited from

ImageBaseProps.transparency

underline?

optional underline?: object

Defined in: src/types/text.ts:267

underline properties

PowerPoint: Font > Color & Underline > Underline Style/Underline Color
style is the full ST_TextUnderlineType enumeration (ECMA-376 §20.1.10.81)
'none' is the explicit off: it writes a:rPr/@u="none", which overrides an underline the run would otherwise inherit from its list style, placeholder, layout or master. Omitting the option instead states nothing and lets that inheritance stand — the two are different facts, not two spellings of one.

color?

optional color?: string

style?

optional style?: "none" | "dash" | "dashHeavy" | "dashLong" | "dashLongHeavy" | "dbl" | "dotDash" | "dotDashHeavy" | "dotDotDash" | "dotDotDashHeavy" | "dotted" | "dottedHeavy" | "heavy" | "sng" | "wavy" | "wavyDbl" | "wavyHeavy" | "words"

Default

(unset) inherit

Inherited from

TableCellProps.underline

valign?

optional valign?: VAlign

Defined in: src/types/text.ts:293

vertical alignment

Default

'top'

Inherited from

TableCellProps.valign

vert?

optional vert?: "horz" | "vert" | "vert270" | "wordArtVert" | "eaVert" | "mongolianVert" | "wordArtVertRtl"

Defined in: src/types/text.ts:509

Advanced/legacy escape hatch for the full ST_TextVerticalType range (e.g. eaVert, mongolianVert, wordArtVert). Prefer TextBaseProps.textDirection for the common cases; both map to a:bodyPr@vert.

Inherited from

TextPropsOptions.vert

w?

optional w?: Coord

Defined in: src/types/core.ts:56

Width

inches or percentage

Examples

10.25 // width in inches

'75%' // width as percentage of slide size

Inherited from

ImageBaseProps.w

wrap?

optional wrap?: boolean

Defined in: src/types/text.ts:514

Text wrap

Default

true

Inherited from

TextPropsOptions.wrap

x?

optional x?: Coord

Defined in: src/types/core.ts:35

Horizontal position

inches or percentage

Examples

10.25 // position in inches

'75%' // position as percentage of slide size

Inherited from

ImageBaseProps.x

y?

optional y?: Coord

Defined in: src/types/core.ts:42

Vertical position

inches or percentage

Examples

10.25 // position in inches

'75%' // position as percentage of slide size

Inherited from

ImageBaseProps.y

Interface: ObjectOptions ​

Extends ​

Properties ​

_bodyProp? ​

align? ​

anchor? ​

bIns? ​

lIns? ​

numCol? ​

prstTxWarp? ​

rIns? ​

spcCol? ​

tIns? ​

vert? ​

wrap? ​

Inherited from ​

_connectorAdj? ​

_endCxn? ​

idx ​

name ​

_lineIdx? ​

Inherited from ​

_placeholderIdx? ​

_placeholderType? ​

_startCxn? ​

idx ​

name ​

_szAuto? ​

h ​

w ​

adjustHandles? ​

Inherited from ​

align? ​

Default ​

Inherited from ​

altText? ​

Inherited from ​

anchorCtr? ​

Default ​

Inherited from ​

angleRange? ​

Default ​

Inherited from ​

arcThicknessRatio? ​

Default ​

Inherited from ​

autoPageCharWeight? ​

Default ​

Example ​

Inherited from ​

autoPageLineWeight? ​

Default ​

Example ​

Inherited from ​

baseline? ​

Inherited from ​

biLevel? ​

threshold ​

Example ​

Inherited from ​

bold? ​

Default ​

Inherited from ​

border? ​

Inherited from ​

breakLine? ​

Default ​

Inherited from ​

bullet? ​

Union Members ​

Type Literal ​

characterCode? ​

Example ​

color? ​

Example ​

fontFace? ​

Example ​

image? ​

Examples ​

image.data? ​

Interface: ObjectOptions

Extends

Properties

_bodyProp?

align?

anchor?

bIns?

lIns?

numCol?

prstTxWarp?

rIns?

spcCol?

tIns?

vert?

wrap?

Inherited from

_connectorAdj?

_endCxn?

idx

name

_lineIdx?

Inherited from

_placeholderIdx?

_placeholderType?

_startCxn?

idx

name

_szAuto?

h

w

adjustHandles?

Inherited from

align?

Default

Inherited from

altText?

Inherited from

anchorCtr?

Default

Inherited from

angleRange?

Default

Inherited from

arcThicknessRatio?

Default

Inherited from

autoPageCharWeight?

Default

Example

Inherited from

autoPageLineWeight?

Default

Example

Inherited from

baseline?

Inherited from

biLevel?

threshold

Example

Inherited from

bold?

Default

Inherited from

border?

Inherited from

breakLine?

Default

Inherited from

bullet?

Union Members

Type Literal

characterCode?

Example

color?

Example

fontFace?

Example

image?

Examples

image.data?