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" }
]