ts-pptx

Appearance

@shbernal/ts-pptx

@shbernal/ts-pptx / index / TextPropsOptions

Interface: TextPropsOptions ​

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

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

Extends ​

Extended by ​

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

_lineIdx? ​

optional _lineIdx?: number

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

align? ​

optional align?: HAlign

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

Horizontal alignment

Default ​

ts
'left'

Inherited from ​

TextBaseProps.align

altText? ​

optional altText?: string

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

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

baseline? ​

optional baseline?: number

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

bold? ​

optional bold?: boolean

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

Bold style

Default ​

ts
false

Inherited from ​

TextBaseProps.bold

breakLine? ​

optional breakLine?: boolean

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

Add a line-break

Default ​

ts
false

Inherited from ​

TextBaseProps.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 ​
ts
'25BA' // 'BLACK RIGHT-POINTING POINTER' (U+25BA)
color? ​

optional color?: string

Bullet glyph color (separate from the text run color)

Example ​
ts
'FF0000' // red bullet
fontFace? ​

optional fontFace?: string

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

Example ​
ts
'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 ​
ts
image: { path: 'images/star.png' }
ts
image: { data: 'image/png;base64,iVBOR...' }
ts
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 ​
ts
27 // DEF_BULLET_MARGIN
Example ​
ts
10 // Indents text 10 points from bullet
numberStartAt? ​

optional numberStartAt?: number

Number bullets start at

Default ​
ts
1
Example ​
ts
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 ​
ts
'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 ​
ts
100
Example ​
ts
80 // bullet glyph is 80% of the text size
type? ​

optional type?: "number" | "bullet"

Bullet type

Default ​
ts
bullet

Default ​

ts
false

Inherited from ​

TextBaseProps.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 ​

ts
(unset) inherit

Inherited from ​

TextBaseProps.caps

charSpacing? ​

optional charSpacing?: number

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

Character spacing

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 ​

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

Inherited from ​

TextBaseProps.color

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 ​

ts
1

Example ​

ts
2 // flow text into two 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 ​

ts
0

Example ​

ts
10 // 10pt gap between columns

data? ​

optional data?: string

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

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?: ShapeFillProps

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

Shape fill

Examples ​

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"

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

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 TsPptx.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/>. Without registered metrics they fall back to the bare flag (<a:normAutofit/> / <a:spAutoFit/>, which only PowerPoint recomputes on edit) and warn once.

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

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

Flip shape horizontally?

Default ​

ts
false

flipV? ​

optional flipV?: boolean

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

Flip shape vertical?

Default ​

ts
false

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 ​

ts
'Arial' // Arial font

Inherited from ​

TextBaseProps.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 ​

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

Inherited from ​

TextBaseProps.fontFaceEA

fontSize? ​

optional fontSize?: number

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

Font size

Example ​

ts
12 // Font size 12

Inherited from ​

TextBaseProps.fontSize

glow? ​

optional glow?: TextGlowProps

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

h? ​

optional h?: Coord

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

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

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

Text highlight color (hex format)

Example ​

ts
'FFFF00' // yellow

Inherited from ​

TextBaseProps.highlight

optional hyperlink?: HyperlinkProps

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

indentLevel? ​

optional indentLevel?: number

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

isTextBox? ​

optional isTextBox?: boolean

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

italic? ​

optional italic?: boolean

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

italic style

Default ​

ts
false

Inherited from ​

TextBaseProps.italic

lang? ​

optional lang?: string

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

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

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

lineSpacing? ​

optional lineSpacing?: number

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

Line spacing (pt)

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

Example ​

ts
28 // 28pt

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 ​

ts
1.5 // 1.5X line spacing

margin? ​

optional margin?: Margin

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

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

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 ​

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

Inherited from ​

ObjectNameProps.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 ​

ts
'Object 1'

Example ​

ts
'Antenna Design 9'

Inherited from ​

ObjectNameProps.objectName

outline? ​

optional outline?: object

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

color ​

color: string

size ​

size: number

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 ​

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

Inherited from ​

TextBaseProps.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 ​

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

Inherited from ​

TextBaseProps.paraMarginLeft

paraSpaceAfter? ​

optional paraSpaceAfter?: number

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

paraSpaceBefore? ​

optional paraSpaceBefore?: number

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

path? ​

optional path?: string

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

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?: string

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

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.

Example ​

ts
'title'

See ​

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

rectRadius? ​

optional rectRadius?: number

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

Rounded rectangle radius (only for ShapeType.roundRect)

  • values: 0.0 to 1.0

Default ​

ts
0

rotate? ​

optional rotate?: number

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

Rotation (degrees)

  • range: -360 to 360

Default ​

ts
0

Example ​

ts
180 // rotate 180 degrees

rtlMode? ​

optional rtlMode?: boolean

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

Whether to enable right-to-left mode

Default ​

ts
false

shadow? ​

optional shadow?: ShadowProps

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

shape? ​

optional shape?: SHAPE_NAME

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

softBreakBefore? ​

optional softBreakBefore?: boolean

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

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"

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 ​

ts
(unset) inherit

subscript? ​

optional subscript?: boolean

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

superscript? ​

optional superscript?: boolean

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

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 ​

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"

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

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

Default ​

ts
'horz'

Inherited from ​

TextBaseProps.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 ​

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

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

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?: 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 ​

ts
(unset) inherit

Inherited from ​

TextBaseProps.underline

valign? ​

optional valign?: VAlign

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

Vertical alignment

Default ​

ts
middle

Overrides ​

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

w? ​

optional w?: Coord

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

Width

  • inches or percentage

Examples ​

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

Inherited from ​

PositionProps.w

wrap? ​

optional wrap?: boolean

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

Text wrap

Default ​

ts
true

x? ​

optional x?: Coord

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

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

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

Vertical position

  • inches or percentage

Examples ​

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

Inherited from ​

PositionProps.y