PPTX
Animations
Add entrance, exit, emphasis, and motion path animations to shapes
Add animation effects to shapes to control how they appear and behave during a presentation.
#Basic Usage
Animations live at the slide level, not on shapes — CT_Shape has no timing
child in the XSD. Each slide exposes an animations array whose entries carry a
shapeId (the target shape's cNvPr id) plus the animation fields inline:
import { generatePresentation } from "@office-open/pptx";
{
"slides": [
{
"children": [
{
"shape": {
"id": 2,
"x": "1.3cm",
"y": "1.3cm",
"width": "15.9cm",
"height": "6.6cm",
"textBody": { "text": "Animated shape" }
}
}
],
"animations": [{ "shapeId": 2, "type": "fade", "duration": 800 }]
}
]
}
{
children: [
{
shape: {
id: 2,
x: "1.3cm",
y: "1.3cm",
width: "15.9cm",
height: "6.6cm",
textBody: { text: "Animated shape" },
},
},
],
animations: [{ shapeId: 2, type: "fade", duration: 800 }],
}
Each animations entry pairs a shapeId with the animation preset fields. The
shapeId matches the id set on the target shape's NonVisualDrawingProperties
(the cNvPr id), which you assign via shape.id; the remaining fields are the
preset documented in the type-specific sections below.
#Targeting Shapes
Fresh documents can reference the target by shapeName instead — the library
resolves it to the shape's cNvPr id at compile time against the shapes of the
same slide:
{
"children": [
{
"shape": {
"name": "Hero",
"x": "1.3cm",
"y": "1.3cm",
"width": "15.9cm",
"height": "6.6cm",
"textBody": {
"text": "Named"
}
}
}
],
"animations": [
{
"shapeName": "Hero",
"type": "fade",
"duration": 800
}
]
}
shapeName is the authoring channel: names stay stable while ids renumber, and
an unknown or duplicated name throws at compile time instead of emitting a
dangling spTgt @spid. shapeId is the round-trip channel (parsed sources keep
their source ids) and wins when both are set.
#Animation Types
#Entrance Animations (class: "entrance", default)
| Type | Description | Supported Directions |
|---|---|---|
appear | Instantly appear | — |
fade | Fade in | — |
fly | Fly in from edge | left, right, up, down |
wipe | Wipe in from edge | left, right, up, down |
dissolve | Dissolve in | — |
split | Split in | horizontal, vertical |
blinds | Blinds effect | horizontal, vertical |
checker | Checkerboard | horizontal, vertical |
randomBars | Random bars | horizontal, vertical |
wheel | Wheel spokes | — |
zoom | Zoom in | — |
cover | Cover from edge | left, right, up, down |
push | Push from edge | left, right, up, down |
strips | Strips from corner | left, right, up, down |
#Exit Animations (class: "exit")
Same types as entrance, but with class: "exit":
[
{ "shapeName": "Title", "type": "fade", "class": "exit", "duration": 800 },
{ "shapeName": "Title", "type": "fly", "class": "exit", "direction": "right" }
]
#Emphasis Animations (class: "emphasis")
emphasisType | Description |
|---|---|
growShrink | Scale up then back |
spin | Full rotation |
colorChange | Change color (requires color) |
transparency | Fade to semi-transparent |
boldFlash | Bold text flash |
wave | Wave effect |
pulse | Pulse effect |
growWithTurn | Grow with rotation |
[
{ "shapeName": "Title", "class": "emphasis", "emphasisType": "growShrink", "duration": 800 },
{ "shapeName": "Title", "class": "emphasis", "emphasisType": "spin", "duration": 1000 },
{ "shapeName": "Title", "class": "emphasis", "emphasisType": "colorChange", "color": "FF0000" }
]
#Motion Path Animations
pathType | Description |
|---|---|
line | Straight line |
arc | Arc curve |
circle | Circular path |
curve | S-curve |
figureEight | Figure-eight |
bounce | Bounce path |
loop | Loop path |
customPath | Custom SVG path (requires path) |
[
{ "shapeName": "Title", "pathType": "circle", "duration": 1500 },
{
"shapeName": "Title",
"pathType": "customPath",
"path": "M 0 0 L 100 0 L 100 100 L 0 100 Z",
"duration": 1200
}
]
#Media Playback (class: "mediaCall")
Trigger audio/video playback on a media shape (a { video } / { audio } child)
with mediaType. The shapeId must point at the media frame:
[
{
"shapeName": "Video 1",
"class": "mediaCall",
"mediaType": "playVideo",
"fullScreen": true,
"showWhenStopped": true
},
{
"shapeName": "Video 1",
"class": "mediaCall",
"mediaType": "playAudio",
"volume": 80,
"mute": false
}
]
| Property | Type | Description |
|---|---|---|
mediaType | "playAudio" | "playVideo" | "play" | Media animation type |
isNarration | boolean | Media is a narration track |
fullScreen | boolean | Play video full-screen |
volume | number | Volume level |
mute | boolean | Mute audio |
showWhenStopped | boolean | Keep the media frame visible when stopped |
#Animation Options
| Property | Type | Default | Description |
|---|---|---|---|
type | AnimationType | "appear" | Animation preset type |
class | "entrance" | "exit" | "emphasis" | "mediaCall" | "entrance" | Animation category |
duration | number | 500 | Duration in milliseconds |
delay | number | 0 | Delay before start in milliseconds |
trigger | AnimationTrigger | "onClick" | How animation is triggered |
direction | AnimationDirection | — | Direction of the animation |
emphasisType | EmphasisType | — | Emphasis animation type (class="emphasis") |
pathType | PathAnimationType | — | Motion path type |
path | string | — | Custom SVG path string |
speed | number | — | Speed multiplier |
repeatCount | number | — | Number of repetitions |
autoReverse | boolean | false | Auto-reverse after completion |
color | string | — | Target color for colorChange |
pathEditMode | "relative" | "fixed" | "none" | — | Motion path edit mode |
rotationAngle | number | — | Motion path rotation in 1/60000ths of a degree (p:animRot @rAng; passed through raw) |
motionFrom | { x: string; y: string } | — | Motion path start point |
motionRotationCenter | { x: string; y: string } | — | Motion rotation center |
zoomContents | boolean | false | Zoom contents during a scale animation |
#Trigger Modes
[
{ "shapeName": "Title", "type": "fade", "trigger": "onClick" },
{ "shapeName": "Title", "type": "fade", "trigger": "withPrevious" },
{ "shapeName": "Title", "type": "fade", "trigger": "afterPrevious" }
]