ts-pptx

Appearance

Interface: PlaceholderProps ​

A layout placeholder's options. They reach the slide objects that fill the placeholder as text options, so beside the text formatting a placeholder takes the shape fill (an image fill included) and the hyperlink a text box does, and bullet through TextBaseProps.

Extends ​

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

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 (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.

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 ​

ts
false

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

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

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

Inherited from ​

TextPropsOptions.fill

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

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 ​

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

h? ​

optional h?: Coord

Height

  • inches or percentage

Examples ​

ts
10.25 // height in inches
ts
'75%' // height as percentage of slide size

Inherited from ​

PositionProps.h

highlight? ​

optional highlight?: string

Text highlight color (hex format)

Example ​

ts
'FFFF00' // yellow

Inherited from ​

TextBaseProps.highlight

optional hyperlink?: HyperlinkProps

Inherited from ​

TextPropsOptions.hyperlink

italic? ​

optional italic?: boolean

italic style

Default ​

ts
false

Inherited from ​

TextBaseProps.italic

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

margin? ​

optional margin?: Margin

margin (inches) — text-frame internal margin; a value >= 1 warns as a likely legacy points value

name ​

name: string

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

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

rectRadius? ​

optional rectRadius?: number

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

  • resolved against the shorter side of the placeholder 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

shape? ​

optional shape?: SHAPE_NAME

Preset shape geometry for this placeholder (e.g. 'roundRect')

Default ​

ts
'rect'

softBreakBefore? ​

optional softBreakBefore?: boolean

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

Default ​

ts
false

Inherited from ​

TextBaseProps.softBreakBefore

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

type ​

type: "media" | "body" | "title" | "chart" | "pic" | "tbl"

underline? ​

optional underline?: object

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" | "words" | "sng" | "dbl" | "heavy" | "dotted" | "dottedHeavy" | "dash" | "dashHeavy" | "dashLong" | "dashLongHeavy" | "dotDash" | "dotDashHeavy" | "dotDotDash" | "dotDotDashHeavy" | "wavy" | "wavyHeavy" | "wavyDbl"

Default ​

ts
(unset) inherit

Inherited from ​

TextBaseProps.underline

valign? ​

optional valign?: VAlign

vertical alignment

Default ​

ts
'top'

Inherited from ​

TextBaseProps.valign

w? ​

optional w?: Coord

Width

  • inches or percentage

Examples ​

ts
10.25 // width in inches
ts
'75%' // width as percentage of slide size

Inherited from ​

PositionProps.w

x? ​

optional x?: Coord

Horizontal position

  • inches or percentage

Examples ​

ts
10.25 // position in inches
ts
'75%' // position as percentage of slide size

Inherited from ​

PositionProps.x

y? ​

optional y?: Coord

Vertical position

  • inches or percentage

Examples ​

ts
10.25 // position in inches
ts
'75%' // position as percentage of slide size

Inherited from ​

PositionProps.y