pptx-ts

Interface: ImageBaseProps ​

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 ​

altText? ​

optional altText?: string

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..."
  • omitted, the picture's descr is empty, as PowerPoint writes it; the source path or URL is never used

Overrides ​

ObjectNameProps.altText

biLevel? ​

optional biLevel?: object

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 ​

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

clrChange? ​

optional clrChange?: object

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 ​

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

crop? ​

optional crop?: object

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

  • each value is the percent (at most 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
  • a negative value pads that edge with empty space instead, as PowerPoint's Fit crop and sizing: 'contain' do
  • 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 trimmed from the bottom edge of the source image; negative pads it.

Default ​
ts
0

l? ​

optional l?: number

Percent trimmed from the left edge of the source image; negative pads it.

Default ​
ts
0

r? ​

optional r?: number

Percent trimmed from the right edge of the source image; negative pads it.

Default ​
ts
0

t? ​

optional t?: number

Percent trimmed from the top edge of the source image; negative pads it.

Default ​
ts
0

Example ​

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

duotone? ​

optional duotone?: object

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 ​

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

flipH? ​

optional flipH?: boolean

Flip horizontally?

Default ​

ts
false

flipV? ​

optional flipV?: boolean

Flip vertical?

Default ​

ts
false

grayscale? ​

optional grayscale?: boolean

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 ​

ts
false

Example ​

ts
true // desaturate the image

h? ​

optional h?: Coord | null

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

Inherited from ​

PlaceholderPositionProps.h

optional hyperlink?: HyperlinkProps

line? ​

optional line?: ShapeLineProps

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 ​

ts
{ color: '0088CC', width: 2 }                   // 2pt blue border
ts
{ color: '666666', width: 1, dashType: 'dash' } // dashed gray border

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

placeholder? ​

optional placeholder?: PlaceholderOption

Name of a picture placeholder defined on the slide layout/master to populate, or a PlaceholderBinding that states the p:ph to write

  • 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
  • a name that matches none writes no p:ph; a binding's idx or type writes one regardless

Examples ​

ts
'picph'
ts
{ type: 'pic', idx: 13 }

See ​

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

points? ​

optional points?: GeometryPoint[]

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 ​

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

rectRadius? ​

optional rectRadius?: number

Corner radius (inches) of the clip 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

Image rotation (degrees)

  • range: -360 to 360

Default ​

ts
0

Example ​

ts
180 // rotate image 180 degrees

rounding? ​

optional rounding?: boolean

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

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

Default ​

ts
false

shadow? ​

optional shadow?: ShadowProps

Shadow Props

  • MS-PPT > Format Picture > Shadow

Example ​

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

shape? ​

optional shape?: SHAPE_NAME

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 ​

ts
'roundRect' // rounded-rectangle avatar
ts
'hexagon'   // hexagonal photo

shapeAdjust? ​

optional shapeAdjust?: ShapeAdjustValue | ShapeAdjustValue[]

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 ​

ts
{ name: 'adj', value: 0.25 }

sizing? ​

optional sizing?: object

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 ​
ts
10.25 // position in inches
ts
'75%' // position as percentage of slide size

type ​

type: "contain" | "cover" | "crop" | "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 ​
ts
10.25 // position in inches
ts
'75%' // position as percentage of slide size

x? ​

optional x?: Coord

Offset from left to crop image

  • crop only
  • inches or percentage
Examples ​
ts
10.25 // position in inches
ts
'75%' // position as percentage of slide size

y? ​

optional y?: Coord

Offset from top to crop image

  • crop only
  • inches or percentage
Examples ​
ts
10.25 // position in inches
ts
'75%' // position as percentage of slide size

svg? ​

optional svg?: string

Raw SVG markup to embed as the image source

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

Example ​

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

transparency? ​

optional transparency?: number

Transparency (percent)

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

Default ​

ts
0

Example ​

ts
25 // 25% transparent

w? ​

optional w?: Coord | null

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

Inherited from ​

PlaceholderPositionProps.w

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