Appearance
Abstract Class: Shape ​
Common base for every shape in a shape tree — a slide's, a layout's, or a master's.
Extended by ​
Constructors ​
Constructor ​
new Shape(
element,host):Shape
Parameters ​
| Parameter | Type | Description |
|---|---|---|
element | Element | - |
host | ShapeHost | The part that owns this shape's tree — a Slide, a SlideLayout, or a SlideMaster. Narrow it with instanceof when you need the concrete class; ShapeHost.partName tells the tiers apart without one. |
Returns ​
Shape
Properties ​
host ​
readonlyhost:ShapeHost
The part that owns this shape's tree — a Slide, a SlideLayout, or a SlideMaster. Narrow it with instanceof when you need the concrete class; ShapeHost.partName tells the tiers apart without one.
shapeType ​
abstractreadonlyshapeType:ShapeType
Which concrete shape kind this is.
Accessors ​
absoluteFrame ​
Get Signature ​
get absoluteFrame():
AbsoluteFrame|null
This shape's position, size, and effective orientation in slide-absolute EMU/degrees, composing every enclosing group transform.
left/top/width/height report a group child's geometry in its group's child coordinate space (a:chOff/a:chExt), which is not directly placeable on the slide. This getter walks the p:grpSp ancestor chain outward, mapping the box through each group's off + (p - chOff) * (ext / chExt) transform, then composing group flips and rotations about the group centre. For a shape already at slide level the box equals its own { left, top, width, height }, while rotation/flipH/flipV equal the shape's own transform values.
null when the shape (or any enclosing group) has no own transform, or a group's a:chExt is degenerate (zero) — there is then no resolvable frame. absoluteFrameFailure says which of those it was.
A rotated shape's returned left/top remain PowerPoint's unrotated placement box (the same box PowerPoint writes after Ungroup), with the effective rotation exposed separately.
Returns ​
AbsoluteFrame | null
absoluteFrameFailure ​
Get Signature ​
get absoluteFrameFailure():
AbsoluteFrameFailure|null
Why absoluteFrame is null, or null when it resolved.
absoluteFrame reports one null for three different situations, and only a caller that wants to report the unresolvable shape needs them apart — an inherited placeholder box is ordinary, a group with no usable a:xfrm is not. The distinction is not recoverable from the null, and re-deriving it means walking the same ancestry a second time, so it is named here instead. See AbsoluteFrameFailure for what each value means.
Returns ​
AbsoluteFrameFailure | null
adjustValues ​
Get Signature ​
get adjustValues():
Record<string,string>
Preset-geometry adjustment values (spPr/a:prstGeom/a:avLst/a:gd) as a name → formula map, e.g. { adj: 'val 16667' }. Empty when the shape has no adjust handles (or uses custom geometry). Pair with presetGeometry.
Returns ​
Record<string, string>
customGeometry ​
Get Signature ​
get customGeometry():
CustomGeometry|null
Custom freeform geometry (spPr/a:custGeom/a:pathLst), or null when the shape uses preset geometry / none. The faithful, multi-path counterpart of presetGeometry: each a:path keeps its own path-unit viewport (w/h) and ordered GeometryCommands. Coordinates are raw path-unit integers, not EMU — pair the path w/h with the shape's box size to map them into slide space.
Not an auto-shape-only property either: a picture clipped to a freeform (what PowerPoint writes when Merge Shapes intersects a picture with a shape, and what addImage({ points }) writes) carries its clip here. A group reads null.
Returns ​
CustomGeometry | null
description ​
Get Signature ​
get description():
string|null
The shape's alt-text description (p:cNvPr/@descr), or null when unset. This is the accessibility primitive a screen reader announces; an audit or accessible-export tool reads it here. Distinct from name, which is the authoring-time shape name and is never surfaced to assistive tech.
Returns ​
string | null
Set Signature ​
set description(
value):void
Set (or clear, with '') the alt-text description. Requires the shape's p:cNvPr to exist, which every well-formed shape carries.
Parameters ​
| Parameter | Type |
|---|---|
value | string |
Returns ​
void
element_ ​
Get Signature ​
get element_():
Element
Escape hatch: the underlying shape element. After mutating it call markDirty, or save() writes the original bytes.
Returns ​
Element
fillColor ​
Get Signature ​
get fillColor():
string|null
Explicit RGB fill colour as a 6-hex string (spPr/a:solidFill/a:srgbClr/@val), or null.
Returns ​
string | null
Set Signature ​
set fillColor(
value):void
Parameters ​
| Parameter | Type |
|---|---|
value | string | null |
Returns ​
void
fillNoFill ​
Get Signature ​
get fillNoFill():
boolean
true when the shape sets an explicit no-fill (spPr/a:noFill) — a deliberately transparent surface. The fill-side counterpart of lineNoFill, and the only accessor that separates it from a shape carrying no fill child at all (one inheriting through p:style/a:fillRef): every other fill accessor — fillColor, fillSchemeColor, resolvedFill, gradientFill, patternFill, pictureFill — reports null for both. The two paint completely differently, so a consumer that cannot tell them apart paints a transparent shape in the theme's accent colour.
Returns ​
boolean
fillSchemeColor ​
Get Signature ​
get fillSchemeColor():
string|null
Theme colour token when the fill is a scheme colour (a:solidFill/a:schemeClr/@val, e.g. accent2), or null.
Returns ​
string | null
Set Signature ​
set fillSchemeColor(
value):void
Parameters ​
| Parameter | Type |
|---|---|
value | string | null |
Returns ​
void
flipH ​
Get Signature ​
get flipH():
boolean
Whether the shape is flipped horizontally (a:xfrm/@flipH); false when unset or when the shape has no own transform. This is the shape's own horizontal flip; use absoluteFrame for the effective value after enclosing group transforms are composed.
Returns ​
boolean
flipV ​
Get Signature ​
get flipV():
boolean
Whether the shape is flipped vertically (a:xfrm/@flipV); false when unset or when the shape has no own transform. This is the shape's own vertical flip; use absoluteFrame for the effective value after enclosing group transforms are composed.
Returns ​
boolean
glow ​
Get Signature ​
get glow():
Glow|null
The shape's glow halo (spPr/a:effectLst/a:glow), resolved against the host's theme, or null when the shape has no glow. The write-side glow option is a text glow in run properties, so it does not read back here.
Returns ​
Glow | null
gradientFill ​
Get Signature ​
get gradientFill():
GradientFill|null
The shape's gradient fill with its geometry (spPr/a:gradFill), or null when the fill is not a gradient. Unlike gradientStops (stops only), this also carries the linear GradientFill.angleDeg or the GradientFill.path shape — the geometry a faithful replica needs and which the bare stop list omits.
Returns ​
GradientFill | null
gradientStops ​
Get Signature ​
get gradientStops():
GradientStop[] |null
Gradient fill stops (spPr/a:gradFill/a:gsLst/a:gs) in document order, or null when the shape's fill is not a gradient. Each stop carries its position (0–1, from @pos in thousandths of a percent) and either an explicit color (hex) or a schemeColor token, mirroring the fillColor / fillSchemeColor split for solid fills.
Returns ​
GradientStop[] | null
hasTextFrame ​
Get Signature ​
get hasTextFrame():
boolean
Whether this shape can hold text (only p:sp does in this read model).
Returns ​
boolean
height ​
Get Signature ​
get height():
number|null
Height in EMU (a:ext/@cy), or null when the shape has no own transform.
Returns ​
number | null
Set Signature ​
set height(
value):void
Parameters ​
| Parameter | Type |
|---|---|
value | number |
Returns ​
void
hidden ​
Get Signature ​
get hidden():
boolean
Whether the shape is explicitly hidden (p:cNvPr/@hidden="1"); false when the attribute is unset. A hidden shape stays in the slide XML but is not rendered — decks use it as a fallback layer (e.g. a duotone-recolour source sitting behind the visible icon), so a faithful reader must distinguish it from the drawn shapes.
Returns ​
boolean
hyperlink ​
Get Signature ​
get hyperlink():
Hyperlink|null
The shape's own click hyperlink (p:cNvPr/a:hlinkClick), or null when it carries none.
This is the link PowerPoint's Insert > Link puts on a whole shape, as opposed to the one a Run carries on a span of text. It is the same element, read the same way, and it had no reader at all -- so a linked shape read back as an ordinary one and a replica lost the link with nothing to say so. addShape, addText and addImage all take hyperlink.
A URL link resolves its @r:id to the external target; a slide jump resolves it to the linked slide's partname and reports ppaction://hlinksldjump as its action. An action-only link (a slide-show navigation button) has no @r:id and resolves to neither.
Returns ​
Hyperlink | null
id ​
Get Signature ​
get id():
number|null
Drawing id (p:cNvPr/@id), or null if absent.
Returns ​
number | null
innerShadow ​
Get Signature ​
get innerShadow():
InnerShadow|null
The shape's inner shadow (spPr/a:effectLst/a:innerShdw), resolved against the host's theme, or null when the shape has no inner shadow. The inset counterpart of shadow: the write-side shadow: { type: 'inner' } emits it, and it is invisible in geometry/fill alone.
Returns ​
InnerShadow | null
isDecorative ​
Get Signature ​
get isDecorative():
boolean
Whether the shape is flagged decorative (p:cNvPr/a:extLst/a:ext uri {C183D7F6-…} / adec:decorative@val), PowerPoint's "Mark as decorative" — a purely visual element assistive tech should skip. false when the extension is absent. A decorative shape typically has no description; the two are alternatives, not companions.
Returns ​
boolean
left ​
Get Signature ​
get left():
number|null
Left edge in EMU (a:off/@x), or null when the shape has no own transform.
Returns ​
number | null
Set Signature ​
set left(
value):void
Parameters ​
| Parameter | Type |
|---|---|
value | number |
Returns ​
void
lineAlign ​
Get Signature ​
get lineAlign():
string|null
The line alignment (spPr/a:ln/@algn) as the raw OOXML token — 'ctr' (centred on the shape's outline) or 'in' (inset, drawn wholly inside it) — or null when unset. It shifts a thick outline by half its width, so it changes where the border sits relative to the fill.
Returns ​
string | null
lineCap ​
Get Signature ​
get lineCap():
string|null
The line end cap (spPr/a:ln/@cap) as the raw OOXML token — 'flat', 'rnd' (round) or 'sq' (square) — or null when unset (PowerPoint's default is flat). The write API authors this attribute through ShapeLineProps.cap, so without the accessor a deck this library produced could not be read back without losing it.
Not cosmetic on a thick dashed rule: the cap decides whether each dash reads as a rectangle or a lozenge, and it extends every dash by the stroke width. SVG's stroke-linecap is the exact equivalent (flat→butt, rnd→round, sq→square).
Returns ​
string | null
lineColor ​
Get Signature ​
get lineColor():
string|null
Explicit RGB line/border colour (spPr/a:ln/a:solidFill/a:srgbClr/@val), or null.
Returns ​
string | null
Set Signature ​
set lineColor(
value):void
Parameters ​
| Parameter | Type |
|---|---|
value | string | null |
Returns ​
void
lineDash ​
Get Signature ​
get lineDash():
string|null
The line/border dash style (spPr/a:ln/a:prstDash/@val), e.g. 'dash', 'lgDashDot', 'sysDot', or null when the line is solid/unset. A faithful replica of dashed dividers and dashed card borders needs this — it is otherwise invisible in lineColor/lineWidthPt alone.
Returns ​
string | null
lineEnds ​
Get Signature ​
get lineEnds():
LineEnds|null
The shape's line/connector arrowheads (a:ln/a:headEnd + a:tailEnd), or null when neither end carries one. Essential for replicating connectors, whose dot/arrow ends are otherwise invisible in the geometry.
Returns ​
LineEnds | null
lineGradient ​
Get Signature ​
get lineGradient():
GradientFill|null
The shape's line/border gradient stroke (spPr/a:ln/a:gradFill), or null when the line is a solid, absent, or inherited border (see resolvedLine). The line counterpart of gradientFill: a gradient-stroked connector — common for faded process arrows in styled decks — otherwise surfaces only its lineWidthPt, dropping the colour entirely, so a replica cannot reproduce the stroke.
Returns ​
GradientFill | null
lineNoFill ​
Get Signature ​
get lineNoFill():
boolean
true when the shape sets an explicit no-line (spPr/a:ln/a:noFill) — a deliberately border-less shape. Distinct from simply having no a:ln (an inherited line), which resolvedLine cannot tell apart: both report null. A replica that relies on a shadow instead of a border needs to know the border was explicitly suppressed.
Returns ​
boolean
lineSchemeColor ​
Get Signature ​
get lineSchemeColor():
string|null
Theme colour token when the line is a scheme colour (a:ln/a:solidFill/a:schemeClr/@val), or null.
Returns ​
string | null
Set Signature ​
set lineSchemeColor(
value):void
Parameters ​
| Parameter | Type |
|---|---|
value | string | null |
Returns ​
void
lineWidthPt ​
Get Signature ​
get lineWidthPt():
number|null
Line/border width in points (spPr/a:ln/@w is EMU; 12700 EMU = 1pt), or null when unset.
Returns ​
number | null
name ​
Get Signature ​
get name():
string
Shape name (p:cNvPr/@name), or '' if unnamed.
Returns ​
string
patternFill ​
Get Signature ​
get patternFill():
PatternFill|null
The shape's pattern (hatch) fill (spPr/a:pattFill), or null when the fill is not a pattern. Surfaces the PatternFill.preset name and both colours resolved against the host's theme — the pattern counterpart of resolvedFill, which reports null for a non-solid fill and so drops a hatched surface entirely.
Returns ​
PatternFill | null
pictureFill ​
Get Signature ​
get pictureFill():
PictureFill|null
The shape's picture (image) fill (spPr/a:blipFill), or null when the fill is not a picture. The image-fill counterpart of patternFill: a shape whose surface is an image is not a Picture — it is an autoShape with a blip fill — and resolvedFill reports null for one, so without this an image-filled shape reads as unfilled. Carries the embedded image (PictureFill.relId/PictureFill.partName) plus the stretch/tile geometry.
Returns ​
PictureFill | null
placeholder ​
Get Signature ​
get placeholder():
PlaceholderRef|null
This shape's placeholder identity (p:ph type/idx), or null when it is not a placeholder. Only p:sp shapes can be placeholders, so the base implementation always returns null; AutoShape overrides it.
Returns ​
PlaceholderRef | null
presetGeometry ​
Get Signature ​
get presetGeometry():
string|null
Preset geometry name (spPr/a:prstGeom/@prst, e.g. rect), or null for custom geometry or none. Not an auto-shape-only property: PowerPoint gives a picture and a connector a preset geometry too (a p:pic is rect unless it has been cropped to a shape), so it reads off whichever properties element this kind carries. A group has no geometry of its own and reads null.
Returns ​
string | null
reflection ​
Get Signature ​
get reflection():
Reflection|null
The shape's reflection (spPr/a:effectLst/a:reflection), or null when it has none. Read-only: this library authors no reflection, so a replica should carry the part rather than regenerate it — see Reflection.
Returns ​
Reflection | null
resolvedFill ​
Get Signature ​
get resolvedFill():
ResolvedColor|null
The shape's solid fill resolved against the host's theme (Slide.themeContext) to a literal hex — the resolved counterpart of fillColor/fillSchemeColor, which report the raw reference. null when the shape has no a:solidFill (a gradient/none/inherited fill) or the colour cannot be made literal. The returned ResolvedColor carries the base hex and raw transforms, and effectiveHex — the base with its colour transforms (lumMod/shade/…) applied (read that for the final rendered colour).
When the shape carries no explicit spPr fill choice, this falls back to the fill the shape inherits from its p:style a:fillRef (the theme style matrix), resolved the same way the theme: 'preserve' flatten path bakes it.
Returns ​
ResolvedColor | null
resolvedFrame ​
Get Signature ​
get resolvedFrame():
ResolvedFrame|null
This shape's effective position and size in EMU: its own a:xfrm when it has one (left/top/width/height, tagged source: 'own'); otherwise, for a placeholder, the geometry it inherits from the matching layout placeholder, else the master's (tagged accordingly). A non-placeholder shape with no own transform has nothing to inherit from and reads null, as does a placeholder whose layout/master chain defines no matching geometry either.
The writer always emits an explicit a:xfrm on every placeholder it authors, so source reads 'own' for every authored deck; 'layout'/'master' is the case an imported deck exercises, when PowerPoint itself leaves a placeholder's geometry to inherit.
Returns ​
ResolvedFrame | null
resolvedLine ​
Get Signature ​
get resolvedLine():
ResolvedColor|null
The shape's line/border solid fill resolved against the host's theme to a literal hex — the resolved counterpart of lineColor/lineSchemeColor. null when the shape has no a:ln/a:solidFill or it cannot be made literal. Like resolvedFill, the result carries effectiveHex (the base colour with its transforms applied) for the final rendered colour.
When the shape's spPr/a:ln states no fill of its own, this falls back to the line colour the shape inherits from its p:style a:lnRef (the theme style matrix). An a:ln without a fill is not a replacement: PowerPoint layers it over the style line one property at a time, and changing only an outline's weight writes <a:ln w="76200"/> and paints the style colour (test/read/fixtures/shape-line-style-override.pptx).
Returns ​
ResolvedColor | null
rotation ​
Get Signature ​
get rotation():
number|null
Clockwise rotation in degrees (a:xfrm/@rot ÷ 60000), or null when the shape has no own transform. A present xfrm with no @rot reads as 0, so — mirroring left/top/width/height — null ("inherits layout geometry") stays distinct from 0 ("has a transform, not rotated"). The value is faithful to the XML and not normalised to a signed range, so a @rot past 360° (e.g. a negative angle stored as 19216344) reads back greater than 360. This is the shape's own orientation; use absoluteFrame when you need the effective orientation after enclosing group transforms are composed.
Returns ​
number | null
shadow ​
Get Signature ​
get shadow():
OuterShadow|null
The shape's outer drop shadow (spPr/a:effectLst/a:outerShdw), resolved against the host's theme, or null when the shape has no outer shadow. The soft brand shadows the eye reads as "floating" panels live here and are invisible in geometry/fill alone.
Returns ​
OuterShadow | null
softEdge ​
Get Signature ​
get softEdge():
SoftEdge|null
The shape's soft (feathered) edge (spPr/a:effectLst/a:softEdge), or null when it has none. Read-only like reflection: carry, don't regenerate.
Returns ​
SoftEdge | null
text ​
Get Signature ​
get text():
string
Convenience: the shape's full text, or '' if it has none.
Returns ​
string
Set Signature ​
set text(
value):void
Convenience: replace the shape's text with a single run, preserving the first existing run's formatting (see TextFrame.text). Throws when the shape has no text frame. For multiple runs or per-run formatting, edit textFrame.paragraphs[].runs[] directly.
Parameters ​
| Parameter | Type |
|---|---|
value | string |
Returns ​
void
textFrame ​
Get Signature ​
get textFrame():
TextFrame|null
The shape's text frame, or null when it cannot hold text.
Returns ​
TextFrame | null
title ​
Get Signature ​
get title():
string|null
The shape's alt-text title (p:cNvPr/@title), or null when unset. Modern PowerPoint no longer exposes a separate title field (only description + "mark as decorative"), so this is usually null; it survives on decks authored by older PowerPoint or other producers that still write it.
Returns ​
string | null
top ​
Get Signature ​
get top():
number|null
Top edge in EMU (a:off/@y), or null when the shape has no own transform.
Returns ​
number | null
Set Signature ​
set top(
value):void
Parameters ​
| Parameter | Type |
|---|---|
value | number |
Returns ​
void
width ​
Get Signature ​
get width():
number|null
Width in EMU (a:ext/@cx), or null when the shape has no own transform.
Returns ​
number | null
Set Signature ​
set width(
value):void
Parameters ​
| Parameter | Type |
|---|---|
value | number |
Returns ​
void
Methods ​
delete() ​
delete():
void
Remove this shape from its parent (the host's shape tree, or an enclosing group) and mark the owning host's part dirty. The proxy is dead afterwards.
The build animations targeting the shape, or any shape inside a deleted group, go with it, and a connector attached to one of them keeps its geometry with that end unbound. PowerPoint refuses a deck whose animation names a shape that is not on the slide.
Returns ​
void
markDirty() ​
markDirty():
void
Mark the owning host's part dirty so save() reserializes it. Public because element_ hands out the live DOM node: the hatch and the obligation that comes with it belong on the same object.
Returns ​
void
noFill() ​
noFill():
void
Set an explicit <a:noFill/> on the shape — a transparent surface. This is distinct from clearing the fill (fillColor = null), which removes the a:solidFill and lets the fill inherit from the shape's style/placeholder. Read it back with fillNoFill.
Returns ​
void