pptx-ts

Interface: TextPropsOptions ​

PositionProps for an object that can fill a layout placeholder: text, an image, a table or a chart. Each axis also takes null, which leaves it unstated, as omitting it does. With placeholder, an unstated axis comes from the layout placeholder; without one, it takes the object's default. null is how a computed value says "unset" where exactOptionalPropertyTypes refuses undefined.

Example ​

ts
{ placeholder: 'body', x: indent ?? null } // the placeholder's left edge unless indented

Extends ​

Extended by ​

Properties ​

align? ​

optional align?: HAlign

Horizontal alignment

When a shape's text is an array of runs, set this on every run of a paragraph. breakLine is not the only paragraph boundary: two adjacent runs whose align differs start a new one, so stating it on the opening run alone splits the paragraph in two. That is the mirror of bullet, paraMarginLeft and paraIndent, which are read from the opening run only. Neither mistake changes the run count: the only symptom is a differently shaped paragraph, with no error.

Default ​

ts
'left'

Inherited from ​

TextBaseProps.align

altText? ​

optional altText?: string

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

  • serialized to the generated object's p:cNvPr descr attribute
  • PowerPoint: [right-click on the object] > "Edit Alt Text..."

Example ​

ts
'Quarterly revenue bar chart'

Inherited from ​

ObjectNameProps.altText

angleRange? ​

optional angleRange?: [number, number]

Preset-geometry start/end angles for text frames (shape + these build <a:prstGeom> adjustment guides through the shared emitter, and genXmlPresetGeom reads them whether the object is a shape or a styled text frame).

arcThicknessRatio? ​

optional arcThicknessRatio?: number

Preset-geometry block-arc thickness for text frames.

baseline? ​

optional baseline?: number

Baseline shift (a:rPr/@baseline): above zero raises the text, below zero lowers it.

A percent of the font size, so 30 raises the text by 30% (what superscript writes) and -40 lowers it by 40% (what subscript writes). It is written in thousandths of a percent, rounded. 0, like leaving the option out, states no shift. Wins over superscript and subscript when both are set.

bold? ​

optional bold?: boolean

Bold style

Default ​

ts
false

Inherited from ​

TextBaseProps.bold

breakLine? ​

optional breakLine?: boolean

Add a line-break

Default ​

ts
false

Inherited from ​

TextBaseProps.breakLine

bullet? ​

optional bullet?: boolean | "inherit" | TextBulletProps

Add standard or custom bullet

  • use true for standard bullet
  • pass object options for custom bullet
  • false 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
  • omitting the option means 'inherit' on a placeholder definition (defineSlideMaster({ objects })), and on text filling a placeholder the layout defines, which takes the definition's bullet. Anywhere else it means false

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.

When a shape's text is an array of runs, state this on the opening run only. A run that draws a bullet starts a new paragraph by itself, so repeating it (the placement that align requires) turns one three-run paragraph into three one-run paragraphs. A paragraph takes its properties from its first run.

Default ​

false, or 'inherit' on a placeholder

Inherited from ​

TextBaseProps.bullet

caps? ​

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

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 ​

ts
(unset) inherit

Inherited from ​

TextBaseProps.caps

charSpacing? ​

optional charSpacing?: number

Character spacing

color? ​

optional color?: string

Text color

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

Examples ​

ts
'FF0000' // hex color (red)
ts
SchemeColor.text1 // Theme color (Text1)

Inherited from ​

TextBaseProps.color

columns? ​

optional columns?: number

Number of text columns in the text body

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

Default ​

ts
1

Example ​

ts
2 // flow text into two columns

columnSpacing? ​

optional columnSpacing?: number

Spacing between text columns (points)

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

Default ​

ts
0

Example ​

ts
10 // 10pt gap between columns

data? ​

optional data?: string

base64-encoded string

  • Useful for avoiding potential path/server issues

Example ​

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

Inherited from ​

DataOrPathProps.data

fill? ​

optional fill?: FillOption

Shape fill, or a bare Color as shorthand for a solid fill (FillOption).

Examples ​

ts
'FF0000' // hex color (red), shorthand for { color:'FF0000' }
ts
{ color:'FF0000' } // hex color (red)
ts
{ color:'0088CC', transparency:50 } // hex color, 50% transparent
ts
{ color:SchemeColor.accent1 } // theme color Accent1

fit? ​

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

Text fit options

MS-PPT > Format Shape > Shape Options > Text Box > "[unlabeled group]": [3 options below]

  • 'none' = Do not Autofit
  • 'shrink' = Shrink text on overflow
  • 'resize' = Resize shape to fit text

Measured fit: if you register the box's font with PptxTs.registerFontMetrics, both 'shrink' and 'resize' are measured at export time, so the text renders correctly in headless renderers and on plain file-open (no edit/resize needed):

  • 'shrink' computes the largest fontScale at which the wrapped text fits and bakes <a:normAutofit fontScale=…/>.
  • 'resize' computes the height the text needs and bakes it into the shape's a:ext/@cy (adjusting a:off/@y per vertical anchor), the marker being <a:spAutoFit/>. With no metrics registered at all they fall back to the bare flag (<a:normAutofit/> / <a:spAutoFit/>, which only PowerPoint recomputes on edit), with no warning. Once any face is registered, a named face without metrics is measured with a conservative estimate (measure/heuristic-metrics), and a run with no face keeps the bare flag (measure/shrink-unmeasured, measure/resize-unmeasured); each code warns once per write.

Note Bare 'shrink'/'resize' (no metrics) only take effect after editing text / resizing the shape; PowerPoint calculates the result then. The object form of 'shrink' always bakes the explicit values you pass.

Examples ​

ts
'shrink' // measured when metrics are registered; else bare <a:normAutofit/>
ts
'resize' // measured when metrics are registered; else bare <a:spAutoFit/>
ts
{ type: 'shrink', fontScale: 85, lnSpcReduction: 20 } // pre-shrink with explicit values

Default ​

ts
"none"

flipH? ​

optional flipH?: boolean

Flip shape horizontally?

Default ​

ts
false

flipV? ​

optional flipV?: boolean

Flip shape vertical?

Default ​

ts
false

fontFace? ​

optional fontFace?: string

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 ​

ts
'Arial' // Arial font

Inherited from ​

TextBaseProps.fontFace

fontFaceEA? ​

optional fontFaceEA?: string

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

Independent of fontFace: set alone, it writes only <a:ea> and the Latin and complex-script slots keep inheriting. When omitted, <a:ea> inherits the theme East Asian font, which is what PowerPoint does for Latin fonts.

Example ​

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

Inherited from ​

TextBaseProps.fontFaceEA

fontSize? ​

optional fontSize?: number

Font size

Example ​

ts
12 // Font size 12

Inherited from ​

TextBaseProps.fontSize

glow? ​

optional glow?: TextGlowProps

h? ​

optional h?: Coord | null

Height, as PositionProps.h. null leaves it unstated: the layout placeholder's, with placeholder.

Inherited from ​

PlaceholderPositionProps.h

highlight? ​

optional highlight?: string

Text highlight color (hex format)

Example ​

ts
'FFFF00' // yellow

Inherited from ​

TextBaseProps.highlight

optional hyperlink?: HyperlinkProps

indentLevel? ​

optional indentLevel?: number

Outline level of the paragraph (a:p/@lvl): which of the list style's nine levels the paragraph takes its bullet, indent and typography from.

  • range: 0-8, whole numbers only (ST_TextIndentLevelType); anything else is reported under text/invalid-indent-level and ignored
  • 0 is the default and writes no attribute
  • this is the discrete level, not a measurement: paraMarginLeft and paraIndent are the points-valued controls

Default ​

ts
0

isTextBox? ​

optional isTextBox?: boolean

italic? ​

optional italic?: boolean

italic style

Default ​

ts
false

Inherited from ​

TextBaseProps.italic

kerning? ​

optional kerning?: number

Kerning (a:rPr/@kern): the smallest font size, in points, that gets pair kerning. Text at this size or larger is kerned, smaller text is not, and 0 turns kerning off.

  • PowerPoint: Font > Character Spacing > "Kerning for fonts: _ Points and above"
  • range: 0-4000

Example ​

ts
12 // kern text set at 12pt or larger, PowerPoint's own default

Default ​

undefined // no kern, except that a non-zero charSpacing writes kern="0"

lang? ​

optional lang?: string

language

  • ISO 639-1 standard language code

Default ​

ts
'en-US' // english US

Example ​

ts
'fr-CA' // french Canadian

Inherited from ​

TextBaseProps.lang

line? ​

optional line?: ShapeLineProps

lineSpacing? ​

optional lineSpacing?: number

Line spacing (pt)

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

Example ​

ts
28 // 28pt

lineSpacingMultiple? ​

optional lineSpacingMultiple?: number

line spacing multiple (percent)

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

Example ​

ts
1.5 // 1.5X line spacing

margin? ​

optional margin?: Margin

Margin (inches): the text-frame internal margin/padding

  • PowerPoint: Format Shape > Shape Options > Size & Properties > Text Box > Left/Right/Top/Bottom margin (shown in inches)
  • array order is [top, right, bottom, left]
  • a value >= 1 is honored as inches but warns once (it is likely a legacy points value; divide by 72)

Default ​

ts
(unset) PowerPoint's "Normal" internal margin [0.05", 0.1", 0.05", 0.1"]

Examples ​

ts
0 // Top/Right/Bottom/Left margin 0
ts
0.1 // Top/Right/Bottom/Left margin 0.1 inch
ts
[0.05, 0.1, 0.05, 0.1] // top 0.05", right 0.1", bottom 0.05", left 0.1"

objectLock? ​

optional objectLock?: ObjectLockProps

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 ​

ts
{ noMove: true, noResize: true } // pin an object in place
ts
{ noGrp: true } // exclude from grouping

Inherited from ​

ObjectNameProps.objectLock

objectName? ​

optional objectName?: string

Object name

  • used instead of the default name for the object's kind: Text 1, Shape 2, Image 1 and so on, numbered per kind (see docs/reference/object-names.md)
  • PowerPoint: Home > Arrange > Selection Pane...

Example ​

ts
'Antenna Design 9'

Inherited from ​

ObjectNameProps.objectName

outline? ​

optional outline?: object

color ​

color: string

size ​

size: number

paraIndent? ​

optional paraIndent?: number | "inherit"

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 ​

ts
-18 // hang the first line 18pt left of the body text
ts
18 // indent the first line 18pt, prose style
ts
'inherit' // keep the list style's indent, even on a bulleted paragraph

Remarks ​

Read from the opening run of a paragraph, like bullet and unlike align; a value on a continuation run is ignored.

Inherited from ​

TextBaseProps.paraIndent

paraMarginLeft? ​

optional paraMarginLeft?: number | "inherit"

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 ​

ts
36 // body text starts 36pt (0.5in) from the frame's text edge
ts
'inherit' // keep the list style's margin, even on a bulleted paragraph

Remarks ​

Read from the opening run of a paragraph, like bullet and unlike align; a value on a continuation run is ignored.

Inherited from ​

TextBaseProps.paraMarginLeft

paraSpaceAfter? ​

optional paraSpaceAfter?: number

paraSpaceBefore? ​

optional paraSpaceBefore?: number

path? ​

optional path?: string

URL or relative path

Example ​

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

Inherited from ​

DataOrPathProps.path

placeholder? ​

optional placeholder?: PlaceholderOption

Placeholder type

  • when the value matches a placeholder defined on the slide layout/master, this text inherits that placeholder's position and formatting
  • otherwise the text shape is promoted to a standalone placeholder of this type, emitting a real <p:ph type="...">. Use placeholder: 'title' to give a slide an accessible title (PowerPoint's accessibility checker otherwise reports "Missing Slide Title")
  • values: 'title' | 'body' | et. al.
  • a PlaceholderBinding states the p:ph in full: its name binds as the string does, and its type and idx are written whether or not a layout placeholder matches, which is how text fills a placeholder of a layout this deck does not define

The placeholder supplies, it does not impose. Every option this bag states wins; the layout placeholder fills in the ones it leaves out. So { placeholder: 'body' } alone takes the placeholder's frame, anchor, margins, bullet and text style, and { placeholder: 'body', valign: 'top' } takes all of that except the anchor. It matches PowerPoint, where a slide placeholder's XML carries only the properties it overrides and inherits the rest.

The rule is about what the caller wrote, not about what the option bag holds by the time inheritance runs: a value this library defaults on the way past does not count as the caller stating one, and does not beat the layout.

Examples ​

ts
'title'
ts
{ type: 'body', idx: 1 }

See ​

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

points? ​

optional points?: GeometryPoint[]

Custom geometry points when a text frame uses a custom geometry shape.

rectRadius? ​

optional rectRadius?: number

Corner radius (inches) of the text box's shape, for 'roundRect' and the other rounded presets

  • resolved against the shorter side of the box and written as the preset's corner guide
  • not clamped: a radius past half the shorter side is written as given, and PowerPoint draws the corner at its limit
  • omitted, the preset keeps its own radius

rotate? ​

optional rotate?: number

Rotation (degrees)

  • range: -360 to 360

Default ​

ts
0

Example ​

ts
180 // rotate 180 degrees

rtlMode? ​

optional rtlMode?: boolean

Whether to enable right-to-left mode

Default ​

ts
false

shadow? ​

optional shadow?: ShadowProps

Shadow options. Which shadow depends on which bag it is on, and the two are different effects rather than two spellings of one:

  • on the options passed to addText (the shape's bag), it is the shape's drop shadow (p:spPr/a:effectLst), PowerPoint's Shape Effects ▸ Shadow;
  • on a run's own options inside the text array, it is the text shadow (a:rPr/a:effectLst), PowerPoint's Text Effects ▸ Shadow.

A run therefore does not inherit the shape's shadow: PowerPoint's two gestures are independent, and applying both is what darkens a shadow twice. State it in both places to get both, exactly as it takes two actions there.

Examples ​

ts
addText('hi', { shadow }) // the box has a shadow; its glyphs do not
ts
addText([{ text: 'hi', options: { shadow } }]) // the glyphs do; the box does not

shape? ​

optional shape?: SHAPE_NAME

shapeAdjust? ​

optional shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[]

Preset-geometry adjustment guides for text frames.

softBreakBefore? ​

optional softBreakBefore?: boolean

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

Default ​

ts
false

Inherited from ​

TextBaseProps.softBreakBefore

strike? ​

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

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 ​

ts
(unset) inherit

subscript? ​

optional subscript?: boolean

superscript? ​

optional superscript?: boolean

tabStops? ​

optional tabStops?: object[]

tab stops

  • PowerPoint: Paragraph > Tabs > Tab stop position

alignment? ​

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

position ​

position: number

Example ​

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

Inherited from ​

TextBaseProps.tabStops

textDirection? ​

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

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

Default ​

ts
'horz'

Inherited from ​

TextBaseProps.textDirection

textWarp? ​

optional textWarp?: "textNoShape" | "textPlain" | "textStop" | "textTriangle" | "textTriangleInverted" | "textChevron" | "textChevronInverted" | "textRingInside" | "textRingOutside" | "textArchUp" | "textArchDown" | "textCircle" | "textButton" | "textArchUpPour" | "textArchDownPour" | "textCirclePour" | "textButtonPour" | "textCurveUp" | "textCurveDown" | "textCanUp" | "textCanDown" | "textWave1" | "textWave2" | "textDoubleWave1" | "textWave4" | "textInflate" | "textDeflate" | "textInflateBottom" | "textDeflateBottom" | "textInflateTop" | "textDeflateTop" | "textDeflateInflate" | "textDeflateInflateDeflate" | "textFadeRight" | "textFadeLeft" | "textFadeUp" | "textFadeDown" | "textSlantUp" | "textSlantDown" | "textCascadeUp" | "textCascadeDown"

Preset text warp / WordArt shape (<a:bodyPr><a:prstTxWarp prst="..">), which bends the text along a preset path (arch, circle, wave, …): the whole ST_TextShapeType set.

Examples ​

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

Inherited from ​

TextBaseProps.textWarp

transparency? ​

optional transparency?: number

Transparency (percent)

  • MS-PPT > Format Shape > Text Options > Text Fill & Outline > Text Fill > Transparency
  • range: 0-100

Default ​

ts
0

Inherited from ​

TextBaseProps.transparency

underline? ​

optional underline?: boolean | { color?: string; style?: "none" | "words" | "sng" | "dbl" | "heavy" | "dotted" | "dottedHeavy" | "dash" | "dashHeavy" | "dashLong" | "dashLongHeavy" | "dotDash" | "dotDashHeavy" | "dotDotDash" | "dotDotDashHeavy" | "wavy" | "wavyHeavy" | "wavyDbl"; }

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.
  • true is shorthand for { style: 'sng' }, a single line. false states nothing, as omitting the option does, so an inherited underline stands; { style: 'none' } is the explicit off.

Default ​

ts
(unset) inherit

Examples ​

ts
underline: true // single underline
ts
underline: { style: 'dbl', color: 'FF0000' } // red double underline

Inherited from ​

TextBaseProps.underline

valign? ​

optional valign?: VAlign

Vertical alignment

Default ​

ts
middle

Overrides ​

TextBaseProps.valign

vert? ​

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

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.

w? ​

optional w?: Coord | null

Width, as PositionProps.w. null leaves it unstated: the layout placeholder's, with placeholder.

Inherited from ​

PlaceholderPositionProps.w

wrap? ​

optional wrap?: boolean

Text wrap

Default ​

ts
true

x? ​

optional x?: Coord | null

Horizontal position, as PositionProps.x. null leaves it unstated: the layout placeholder's, with placeholder.

Inherited from ​

PlaceholderPositionProps.x

y? ​

optional y?: Coord | null

Vertical position, as PositionProps.y. null leaves it unstated: the layout placeholder's, with placeholder.

Inherited from ​

PlaceholderPositionProps.y