Cheatsheet

The shortest path from “I want to do X” to working code. Each row names the exact function(s) you import. The snippets below the index expand the most common patterns. For prose context see Recipes; for every export see API reference.

Everything lives under the single @office-kit/pptx entry (or @office-kit/pptx/node for the Node fs helpers). The library is fn-only — no classes — so once you know the function name you know how to import it.

Index

Load / save

Slides

Placeholders & text

Shapes

Tables

Pass { coveredText: 'append' } to mergeTableCells to collect the selected cells’ formatted paragraphs in the top-left cell. Splitting leaves that combined text in the top-left cell. The default merge policy preserves text in each covered cell, which becomes visible again after splitting.

Charts

Images

Document metadata

Comments

Diagnostics

Snippets

Each snippet below corresponds to one row above. Imports are explicit so you can copy-paste a single block into your file.

Load + save round-trip

import { loadPresentation, savePresentation } from '@office-kit/pptx';

const pres = await loadPresentation(bytes);
// ...mutate pres...
const out = await savePresentation(pres);

Token-based template fill

import { loadPresentation, replaceTokensInPresentation, savePresentation } from '@office-kit/pptx';

const pres = await loadPresentation(templateBytes);
replaceTokensInPresentation(pres, { name: 'Alice', date: '2026-12-01' });
const out = await savePresentation(pres);

Add a title slide

import {
  addSlide,
  findSlideLayout,
  findSlidePlaceholder,
  loadPresentation,
  savePresentation,
  setShapeText,
} from '@office-kit/pptx';

const pres = await loadPresentation(blankBytes);
const layout = findSlideLayout(pres, 'Title Slide');
if (layout) {
  const slide = addSlide(pres, { layout });
  const t = findSlidePlaceholder(slide, 'ctrTitle') ?? findSlidePlaceholder(slide, 'title');
  if (t) setShapeText(t, 'Hello');
}
const out = await savePresentation(pres);

Add a free-form text box with formatting

import {
  addSlideTextBox,
  inches,
  setShapeRunFormat,
} from '@office-kit/pptx';

const box = addSlideTextBox(slide, {
  x: inches(1),
  y: inches(1),
  w: inches(5),
  h: inches(1),
  text: 'Hello, @office-kit/pptx',
});
setShapeRunFormat(box, 0, 0, { bold: true, size: 28, color: '#C00000', font: 'Calibri' });

Add a preset shape with a fill + shadow

import {
  addSlideShape,
  inches,
  pt,
  setShapeFill,
  setShapeShadow,
} from '@office-kit/pptx';

const star = addSlideShape(slide, {
  preset: 'star5',
  x: inches(1),
  y: inches(2),
  w: inches(2),
  h: inches(2),
  text: '★',
});
setShapeFill(star, '#FFD966');
setShapeShadow(star, {
  blurEmu: pt(6),
  offsetEmu: pt(3),
  angleDeg: 45,
  color: '#000000',
  opacity: 0.4,
});

Add a column chart

import { addSlideChart, inches } from '@office-kit/pptx';

addSlideChart(slide, {
  x: inches(1),
  y: inches(1.5),
  w: inches(8),
  h: inches(4.5),
  spec: {
    kind: 'column',
    categories: ['Q1', 'Q2', 'Q3', 'Q4'],
    series: [{ name: 'Revenue', values: [120, 180, 240, 300] }],
    title: 'FY26',
  },
});

Add a scatter, 3-D or stock chart

Every ECMA-376 plot type is authorable. kind names the data shape; a modifier on the spec picks the variant.

import { addSlideChart, inches } from '@office-kit/pptx';

const box = { x: inches(1), y: inches(1.5), w: inches(8), h: inches(4.5) };

// Scatter / bubble: each series carries its own x channel, `categories` is unused.
addSlideChart(slide, {
  ...box,
  spec: {
    kind: 'scatter',
    categories: [],
    scatterStyle: 'lineMarker',
    series: [
      {
        name: 'Trial A',
        xValues: [1, 2, 3],
        values: [2.5, 4.1, 6.2],
        errorBars: { barType: 'both', amount: { type: 'percentage', value: 10 } },
      },
    ],
    categoryAxisScaling: { min: 0, max: 4 }, // the x axis
  },
});

// 3-D: add `view3D` to bar / column / line / area / pie.
addSlideChart(slide, {
  ...box,
  spec: { kind: 'column', categories, series, view3D: { rotX: 20, rotY: 30 } },
});

// Stock: series are read by position — high, low, close (open first for candlesticks).
addSlideChart(slide, {
  ...box,
  spec: { kind: 'stock', categories: days, series: [open, high, low, close] },
});

Add a table with header + banded rows

import { addSlideTable, inches } from '@office-kit/pptx';

addSlideTable(slide, {
  x: inches(0.7),
  y: inches(1.5),
  w: inches(9),
  h: inches(3),
  rows: [
    ['Quarter', 'Revenue', 'Margin'],
    ['Q1', '$1.2M', '33%'],
    ['Q2', '$1.8M', '50%'],
  ],
  firstRow: true,
  bandRow: true,
});

Insert an image at a fixed size

import { addSlideImage, inches } from '@office-kit/pptx';

addSlideImage(slide, pngBytes, {
  x: inches(1),
  y: inches(1),
  w: inches(3),
  h: inches(2),
});

Add video, audio or an online video

import { addSlideMedia, getShapeMedia, inches } from '@office-kit/pptx';

const box = { x: inches(1), y: inches(1.5), w: inches(8), h: inches(4.5) };

// Embedded video / audio, from bytes. The container is detected from the bytes.
const clip = addSlideMedia(slide, { kind: 'video', data: mp4Bytes, poster: posterPngBytes, ...box });
addSlideMedia(slide, { kind: 'audio', data: mp3Bytes, x: inches(0.5), y: inches(6.5), w: inches(0.6), h: inches(0.6) });

// Online video. YouTube watch / youtu.be / shorts URLs become the embed URL.
addSlideMedia(slide2, { kind: 'online', url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ', ...box });

const media = getShapeMedia(clip);
// { kind: 'video', partName: '/ppt/media/media1.mp4', contentType: 'video/mp4', bytes }
// an online video reads back as { kind: 'online', url }

The shape is a picture showing the poster frame, so setShapeImage replaces the poster. Identical clip bytes are stored once per deck.

Replace an image’s bytes in place

import { getShapeKind, getShapeName, getSlideShapes, getSlides, setShapeImage } from '@office-kit/pptx';

for (const slide of getSlides(pres)) {
  for (const shape of getSlideShapes(slide)) {
    if (getShapeKind(shape) === 'picture' && getShapeName(shape) === 'Logo') {
      setShapeImage(shape, newLogoBytes);
    }
  }
}

Add a hyperlink on text

import { setShapeHyperlink, setShapeTextFormat } from '@office-kit/pptx';

setShapeHyperlink(linkShape, 'https://example.com');
setShapeTextFormat(linkShape, { color: '#0563C1', underline: true });

Set a transition + animation

import { setShapeAnimation, setSlideTransition } from '@office-kit/pptx';

setSlideTransition(slide, { effect: 'fade', speed: 'med' });
setShapeAnimation(shape, { effect: 'fadeIn', durationMs: 700 });

Validate before saving

import { validatePresentation } from '@office-kit/pptx';

const issues = validatePresentation(pres);
for (const i of issues) console.error(i.severity, i.message);

Speaker notes

import { setSlideNotes } from '@office-kit/pptx';

setSlideNotes(slide, 'Open the comments pane to see review.');

Comments

import { addSlideComment, cm } from '@office-kit/pptx';

addSlideComment(slide, {
  author: { name: 'Reviewer', initials: 'R' },
  text: 'Tighten the headline.',
  position: { x: cm(2), y: cm(2) },
});