# 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](/pptx/docs/recipes);
for every export see [API reference](/pptx/api).

> 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

| Task | Functions |
|------|-----------|
| Load a `.pptx` (any env) → `PresentationData` | `loadPresentation` |
| Save a `PresentationData` → `Uint8Array` | `savePresentation` |
| Node convenience: read from / write to disk | `loadPresentationFile` + `savePresentationToFile` (from `@office-kit/pptx/node`) |
| Create an empty package (advanced) | `createPresentation` |

### Slides

| Task | Functions |
|------|-----------|
| Enumerate slides | `getSlides` (or `getSlideAt(pres, i)`) |
| Add a slide on a layout | `findSlideLayout` + `addSlide` |
| Quick blank / title / content slide | `addBlankSlide` / `addTitleSlide` / `addContentSlide` |
| Duplicate, move, swap, reverse | `duplicateSlide` + `moveSlide` + `swapSlides` + `reverseSlides` |
| Remove or sort | `removeSlide` + `sortSlides` |
| Title / hidden flag / layout | `setSlideTitle` + `setSlideHidden` + `setSlideLayout` |
| Solid background color | `setSlideBackground` (or `setSlideBackgroundImage`) |
| Speaker notes | `setSlideNotes` + `getSlideNotes` |
| Transition | `setSlideTransition` |

### Placeholders & text

| Task | Functions |
|------|-----------|
| Find a placeholder by type | `findSlidePlaceholder(slide, 'title')` |
| Bulk-fill placeholders | `setSlidePlaceholders(slide, { title, body, ... })` |
| Token replace across deck or slide | `replaceTokensInPresentation` / `replaceTokensInSlide` |
| Free text replace | `replaceTextInPresentation` / `replaceTextInSlide` |
| Set / get a shape's text | `setShapeText` + `getShapeText` |
| Per-run formatting (bold, size, color) | `setShapeRunFormat` |
| Per-paragraph alignment / level / bullet | `setParagraphAlignment` + `setParagraphLevel` + `setParagraphBullet` |
| Bullets across the whole shape | `setShapeBulletStyle` |

### Shapes

| Task | Functions |
|------|-----------|
| Add a free-form text box | `addSlideTextBox` |
| Add a preset shape (180+ presets) | `addSlideShape` |
| Add a line / connector / arrow | `addSlideLine` + `setShapeStrokeArrow` |
| Add a picture | `addSlideImage` |
| Add video / audio / online video, read it back | `addSlideMedia` + `getShapeMedia` + `findShapesWithMedia` |
| Solid fill / gradient / pattern / image fill | `setShapeFill` + `setShapeGradientFill` + `setShapePatternFill` + `setShapeImageFill` |
| Stroke color / width / dash | `setShapeStroke` + `setShapeStrokeDash` |
| Shadow / glow | `setShapeShadow` + `setShapeGlow` |
| Move / resize / rotate / flip | `setShapePosition` + `setShapeSize` + `setShapeRotation` + `setShapeFlip` |
| Z-order | `bringShapeToFront` + `sendShapeToBack` + `bringShapeForward` + `sendShapeBackward` |
| Hyperlink / click action | `setShapeHyperlink` + `setShapeClickAction` |
| Animation (entrance / exit) | `setShapeAnimation({ effect: 'fadeIn', durationMs: 700 })` |
| Remove a shape | `removeShape` |

### Tables

| Task | Functions |
|------|-----------|
| Add a table | `addSlideTable` |
| Get / set a cell's text | `getTableCellText` + `setTableCellText` |
| Cell fill / alignment / text format | `setTableCellFill` + `setTableCellAlignment` + `setTableCellTextFormat` |
| Insert / remove a row or column | `insertTableRow` + `removeTableRow` + `insertTableColumn` + `removeTableColumn` |
| Resize a row or column | `setTableRowHeight` + `setTableColumnWidth` |
| Merge / split cells | `mergeTableCells` + `splitTableCell` |

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

| Task | Functions |
|------|-----------|
| Add a chart with embedded data | `addSlideChart({ spec: { kind, categories, series } })` |
| Update an existing chart's data | `getShapeChartSpec` + `setChartSpec` |
| Enumerate every chart | `getAllCharts` |

### Images

| Task | Functions |
|------|-----------|
| Replace an image's bytes | `setShapeImage` |
| Crop / opacity / brightness / contrast | `setShapeImageCrop` + `setShapeImageOpacity` + `setShapeImageBrightness` + `setShapeImageContrast` |

### Document metadata

| Task | Functions |
|------|-----------|
| Title / Author / Subject / Keywords | `setCoreProperties` |
| App / Company / Manager | `setExtendedProperties` |
| Thumbnail image | `setThumbnail` |
| Bump revision on save | `incrementRevision` + `touchModified` |

### Comments

| Task | Functions |
|------|-----------|
| Add / remove a comment | `addSlideComment` + `removeSlideComment` |
| List comments | `getSlideComments` (or `getAllComments`) |

### Diagnostics

| Task | Functions |
|------|-----------|
| Validate the package | `validatePresentation(pres)` |
| Inspect parts list | `listPackageParts` + `readPackagePart` |
| Strip unused media | `compactPackage` |

## 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

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

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

### Token-based template fill

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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.

```ts
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] },
});
```

| Kind                                   | Element                       | Modifier                                     |
| -------------------------------------- | ----------------------------- | -------------------------------------------- |
| `bar` `column` `line` `area`           | bar / line / area chart       | `view3D` → the 3-D element                   |
| `pie`                                  | pie chart                     | `view3D` → 3-D pie, `ofPie` → pie-of-pie     |
| `doughnut` `radar` `scatter` `stock`   | their own element             | `radarStyle`, `scatterStyle`, `upDownBars`   |
| `bubble`                               | bubble chart                  | `bubble3D`, `bubbleScale`                    |
| `surface`                              | 3-D surface                   | `surfaceContour` → contour, `surfaceWireframe` |

### Add a table with header + banded rows

```ts
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

```ts
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

```ts
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

```ts
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

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

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

### Set a transition + animation

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

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

### Validate before saving

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

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

### Speaker notes

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

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

### Comments

```ts
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) },
});
```