1# PptxGenJS Tutorial
2 
3## Setup & Basic Structure
4 
5```javascript
6const pptxgen = require("pptxgenjs");
7 
8let pres = new pptxgen();
9pres.layout = 'LAYOUT_16x9';  // or 'LAYOUT_16x10', 'LAYOUT_4x3', 'LAYOUT_WIDE'
10pres.author = 'Your Name';
11pres.title = 'Presentation Title';
12 
13let slide = pres.addSlide();
14slide.addText("Hello World!", { x: 0.5, y: 0.5, fontSize: 36, color: "363636" });
15 
16pres.writeFile({ fileName: "Presentation.pptx" });
17```
18 
19## Layout Dimensions
20 
21Slide dimensions (coordinates in inches):
22- `LAYOUT_16x9`: 10" × 5.625" (default)
23- `LAYOUT_16x10`: 10" × 6.25"
24- `LAYOUT_4x3`: 10" × 7.5"
25- `LAYOUT_WIDE`: 13.3" × 7.5"
26 
27---
28 
29## Text & Formatting
30 
31```javascript
32// Basic text
33slide.addText("Simple Text", {
34  x: 1, y: 1, w: 8, h: 2, fontSize: 24, fontFace: "Arial",
35  color: "363636", bold: true, align: "center", valign: "middle"
36});
37 
38// Character spacing (use charSpacing, not letterSpacing which is silently ignored)
39slide.addText("SPACED TEXT", { x: 1, y: 1, w: 8, h: 1, charSpacing: 6 });
40 
41// Rich text arrays
42slide.addText([
43  { text: "Bold ", options: { bold: true } },
44  { text: "Italic ", options: { italic: true } }
45], { x: 1, y: 3, w: 8, h: 1 });
46 
47// Multi-line text (requires breakLine: true)
48slide.addText([
49  { text: "Line 1", options: { breakLine: true } },
50  { text: "Line 2", options: { breakLine: true } },
51  { text: "Line 3" }  // Last item doesn't need breakLine
52], { x: 0.5, y: 0.5, w: 8, h: 2 });
53 
54// Text box margin (internal padding)
55slide.addText("Title", {
56  x: 0.5, y: 0.3, w: 9, h: 0.6,
57  margin: 0  // Use 0 when aligning text with other elements like shapes or icons
58});
59```
60 
61**Tip:** Text boxes have internal margin by default. Set `margin: 0` when you need text to align precisely with shapes, lines, or icons at the same x-position.
62 
63---
64 
65## Lists & Bullets
66 
67```javascript
68// ✅ CORRECT: Multiple bullets
69slide.addText([
70  { text: "First item", options: { bullet: true, breakLine: true } },
71  { text: "Second item", options: { bullet: true, breakLine: true } },
72  { text: "Third item", options: { bullet: true } }
73], { x: 0.5, y: 0.5, w: 8, h: 3 });
74 
75// ❌ WRONG: Never use unicode bullets
76slide.addText("• First item", { ... });  // Creates double bullets
77 
78// Sub-items and numbered lists
79{ text: "Sub-item", options: { bullet: true, indentLevel: 1 } }
80{ text: "First", options: { bullet: { type: "number" }, breakLine: true } }
81```
82 
83---
84 
85## Shapes
86 
87```javascript
88slide.addShape(pres.shapes.RECTANGLE, {
89  x: 0.5, y: 0.8, w: 1.5, h: 3.0,
90  fill: { color: "FF0000" }, line: { color: "000000", width: 2 }
91});
92 
93slide.addShape(pres.shapes.OVAL, { x: 4, y: 1, w: 2, h: 2, fill: { color: "0000FF" } });
94 
95slide.addShape(pres.shapes.LINE, {
96  x: 1, y: 3, w: 5, h: 0, line: { color: "FF0000", width: 3, dashType: "dash" }
97});
98 
99// With transparency
100slide.addShape(pres.shapes.RECTANGLE, {
101  x: 1, y: 1, w: 3, h: 2,
102  fill: { color: "0088CC", transparency: 50 }
103});
104 
105// Rounded rectangle (rectRadius only works with ROUNDED_RECTANGLE, not RECTANGLE)
106// ⚠️ Don't pair with rectangular accent overlays — they won't cover rounded corners. Use RECTANGLE instead.
107slide.addShape(pres.shapes.ROUNDED_RECTANGLE, {
108  x: 1, y: 1, w: 3, h: 2,
109  fill: { color: "FFFFFF" }, rectRadius: 0.1
110});
111 
112// With shadow
113slide.addShape(pres.shapes.RECTANGLE, {
114  x: 1, y: 1, w: 3, h: 2,
115  fill: { color: "FFFFFF" },
116  shadow: { type: "outer", color: "000000", blur: 6, offset: 2, angle: 135, opacity: 0.15 }
117});
118```
119 
120Shadow options:
121 
122| Property | Type | Range | Notes |
123|----------|------|-------|-------|
124| `type` | string | `"outer"`, `"inner"` | |
125| `color` | string | 6-char hex (e.g. `"000000"`) | No `#` prefix, no 8-char hex — see Common Pitfalls |
126| `blur` | number | 0-100 pt | |
127| `offset` | number | 0-200 pt | **Must be non-negative** — negative values corrupt the file |
128| `angle` | number | 0-359 degrees | Direction the shadow falls (135 = bottom-right, 270 = upward) |
129| `opacity` | number | 0.0-1.0 | Use this for transparency, never encode in color string |
130 
131To cast a shadow upward (e.g. on a footer bar), use `angle: 270` with a positive offset — do **not** use a negative offset.
132 
133**Note**: Gradient fills are not natively supported. Use a gradient image as a background instead.
134 
135---
136 
137## Images
138 
139### Image Sources
140 
141```javascript
142// From file path
143slide.addImage({ path: "images/chart.png", x: 1, y: 1, w: 5, h: 3 });
144 
145// From URL
146slide.addImage({ path: "https://example.com/image.jpg", x: 1, y: 1, w: 5, h: 3 });
147 
148// From base64 (faster, no file I/O)
149slide.addImage({ data: "image/png;base64,iVBORw0KGgo...", x: 1, y: 1, w: 5, h: 3 });
150```
151 
152### Image Options
153 
154```javascript
155slide.addImage({
156  path: "image.png",
157  x: 1, y: 1, w: 5, h: 3,
158  rotate: 45,              // 0-359 degrees
159  rounding: true,          // Circular crop
160  transparency: 50,        // 0-100
161  flipH: true,             // Horizontal flip
162  flipV: false,            // Vertical flip
163  altText: "Description",  // Accessibility
164  hyperlink: { url: "https://example.com" }
165});
166```
167 
168### Image Sizing Modes
169 
170```javascript
171// Contain - fit inside, preserve ratio
172{ sizing: { type: 'contain', w: 4, h: 3 } }
173 
174// Cover - fill area, preserve ratio (may crop)
175{ sizing: { type: 'cover', w: 4, h: 3 } }
176 
177// Crop - cut specific portion
178{ sizing: { type: 'crop', x: 0.5, y: 0.5, w: 2, h: 2 } }
179```
180 
181### Calculate Dimensions (preserve aspect ratio)
182 
183```javascript
184const origWidth = 1978, origHeight = 923, maxHeight = 3.0;
185const calcWidth = maxHeight * (origWidth / origHeight);
186const centerX = (10 - calcWidth) / 2;
187 
188slide.addImage({ path: "image.png", x: centerX, y: 1.2, w: calcWidth, h: maxHeight });
189```
190 
191### Supported Formats
192 
193- **Standard**: PNG, JPG, GIF (animated GIFs work in Microsoft 365)
194- **SVG**: Works in modern PowerPoint/Microsoft 365
195 
196---
197 
198## Icons
199 
200Use react-icons to generate SVG icons, then rasterize to PNG for universal compatibility.
201 
202### Setup
203 
204```javascript
205const React = require("react");
206const ReactDOMServer = require("react-dom/server");
207const sharp = require("sharp");
208const { FaCheckCircle, FaChartLine } = require("react-icons/fa");
209 
210function renderIconSvg(IconComponent, color = "#000000", size = 256) {
211  return ReactDOMServer.renderToStaticMarkup(
212    React.createElement(IconComponent, { color, size: String(size) })
213  );
214}
215 
216async function iconToBase64Png(IconComponent, color, size = 256) {
217  const svg = renderIconSvg(IconComponent, color, size);
218  const pngBuffer = await sharp(Buffer.from(svg)).png().toBuffer();
219  return "image/png;base64," + pngBuffer.toString("base64");
220}
221```
222 
223### Add Icon to Slide
224 
225```javascript
226const iconData = await iconToBase64Png(FaCheckCircle, "#4472C4", 256);
227 
228slide.addImage({
229  data: iconData,
230  x: 1, y: 1, w: 0.5, h: 0.5  // Size in inches
231});
232```
233 
234**Note**: Use size 256 or higher for crisp icons. The size parameter controls the rasterization resolution, not the display size on the slide (which is set by `w` and `h` in inches).
235 
236### Icon Libraries
237 
238Install: `npm install -g react-icons react react-dom sharp`
239 
240Popular icon sets in react-icons:
241- `react-icons/fa` - Font Awesome
242- `react-icons/md` - Material Design
243- `react-icons/hi` - Heroicons
244- `react-icons/bi` - Bootstrap Icons
245 
246---
247 
248## Slide Backgrounds
249 
250```javascript
251// Solid color
252slide.background = { color: "F1F1F1" };
253 
254// Color with transparency
255slide.background = { color: "FF3399", transparency: 50 };
256 
257// Image from URL
258slide.background = { path: "https://example.com/bg.jpg" };
259 
260// Image from base64
261slide.background = { data: "image/png;base64,iVBORw0KGgo..." };
262```
263 
264---
265 
266## Tables
267 
268```javascript
269slide.addTable([
270  ["Header 1", "Header 2"],
271  ["Cell 1", "Cell 2"]
272], {
273  x: 1, y: 1, w: 8, h: 2,
274  border: { pt: 1, color: "999999" }, fill: { color: "F1F1F1" }
275});
276 
277// Advanced with merged cells
278let tableData = [
279  [{ text: "Header", options: { fill: { color: "6699CC" }, color: "FFFFFF", bold: true } }, "Cell"],
280  [{ text: "Merged", options: { colspan: 2 } }]
281];
282slide.addTable(tableData, { x: 1, y: 3.5, w: 8, colW: [4, 4] });
283```
284 
285---
286 
287## Charts
288 
289```javascript
290// Bar chart
291slide.addChart(pres.charts.BAR, [{
292  name: "Sales", labels: ["Q1", "Q2", "Q3", "Q4"], values: [4500, 5500, 6200, 7100]
293}], {
294  x: 0.5, y: 0.6, w: 6, h: 3, barDir: 'col',
295  showTitle: true, title: 'Quarterly Sales'
296});
297 
298// Line chart
299slide.addChart(pres.charts.LINE, [{
300  name: "Temp", labels: ["Jan", "Feb", "Mar"], values: [32, 35, 42]
301}], { x: 0.5, y: 4, w: 6, h: 3, lineSize: 3, lineSmooth: true });
302 
303// Pie chart
304slide.addChart(pres.charts.PIE, [{
305  name: "Share", labels: ["A", "B", "Other"], values: [35, 45, 20]
306}], { x: 7, y: 1, w: 5, h: 4, showPercent: true });
307```
308 
309### Better-Looking Charts
310 
311Default charts look dated. Apply these options for a modern, clean appearance:
312 
313```javascript
314slide.addChart(pres.charts.BAR, chartData, {
315  x: 0.5, y: 1, w: 9, h: 4, barDir: "col",
316 
317  // Custom colors (match your presentation palette)
318  chartColors: ["0D9488", "14B8A6", "5EEAD4"],
319 
320  // Clean background
321  chartArea: { fill: { color: "FFFFFF" }, roundedCorners: true },
322 
323  // Muted axis labels
324  catAxisLabelColor: "64748B",
325  valAxisLabelColor: "64748B",
326 
327  // Subtle grid (value axis only)
328  valGridLine: { color: "E2E8F0", size: 0.5 },
329  catGridLine: { style: "none" },
330 
331  // Data labels on bars
332  showValue: true,
333  dataLabelPosition: "outEnd",
334  dataLabelColor: "1E293B",
335 
336  // Hide legend for single series
337  showLegend: false,
338});
339```
340 
341**Key styling options:**
342- `chartColors: [...]` - hex colors for series/segments
343- `chartArea: { fill, border, roundedCorners }` - chart background
344- `catGridLine/valGridLine: { color, style, size }` - grid lines (`style: "none"` to hide)
345- `lineSmooth: true` - curved lines (line charts)
346- `legendPos: "r"` - legend position: "b", "t", "l", "r", "tr"
347 
348---
349 
350## Slide Masters
351 
352```javascript
353pres.defineSlideMaster({
354  title: 'TITLE_SLIDE', background: { color: '283A5E' },
355  objects: [{
356    placeholder: { options: { name: 'title', type: 'title', x: 1, y: 2, w: 8, h: 2 } }
357  }]
358});
359 
360let titleSlide = pres.addSlide({ masterName: "TITLE_SLIDE" });
361titleSlide.addText("My Title", { placeholder: "title" });
362```
363 
364---
365 
366## Common Pitfalls
367 
368⚠️ These issues cause file corruption, visual bugs, or broken output. Avoid them.
369 
3701. **NEVER use "#" with hex colors** - causes file corruption
371   ```javascript
372   color: "FF0000"      // ✅ CORRECT
373   color: "#FF0000"     // ❌ WRONG
374   ```
375 
3762. **NEVER encode opacity in hex color strings** - 8-char colors (e.g., `"00000020"`) corrupt the file. Use the `opacity` property instead.
377   ```javascript
378   shadow: { type: "outer", blur: 6, offset: 2, color: "00000020" }          // ❌ CORRUPTS FILE
379   shadow: { type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.12 }  // ✅ CORRECT
380   ```
381 
3823. **Use `bullet: true`** - NEVER unicode symbols like "•" (creates double bullets)
383 
3844. **Use `breakLine: true`** between array items or text runs together
385 
3865. **Avoid `lineSpacing` with bullets** - causes excessive gaps; use `paraSpaceAfter` instead
387 
3886. **Each presentation needs fresh instance** - don't reuse `pptxgen()` objects
389 
3907. **NEVER reuse option objects across calls** - PptxGenJS mutates objects in-place (e.g. converting shadow values to EMU). Sharing one object between multiple calls corrupts the second shape.
391   ```javascript
392   const shadow = { type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 };
393   slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });  // ❌ second call gets already-converted values
394   slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
395 
396   const makeShadow = () => ({ type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 });
397   slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });  // ✅ fresh object each time
398   slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
399   ```
400 
4018. **Don't use `ROUNDED_RECTANGLE` with accent borders** - rectangular overlay bars won't cover rounded corners. Use `RECTANGLE` instead.
402   ```javascript
403   // ❌ WRONG: Accent bar doesn't cover rounded corners
404   slide.addShape(pres.shapes.ROUNDED_RECTANGLE, { x: 1, y: 1, w: 3, h: 1.5, fill: { color: "FFFFFF" } });
405   slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 0.08, h: 1.5, fill: { color: "0891B2" } });
406 
407   // ✅ CORRECT: Use RECTANGLE for clean alignment
408   slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 3, h: 1.5, fill: { color: "FFFFFF" } });
409   slide.addShape(pres.shapes.RECTANGLE, { x: 1, y: 1, w: 0.08, h: 1.5, fill: { color: "0891B2" } });
410   ```
411 
412---
413 
414## Quick Reference
415 
416- **Shapes**: RECTANGLE, OVAL, LINE, ROUNDED_RECTANGLE
417- **Charts**: BAR, LINE, PIE, DOUGHNUT, SCATTER, BUBBLE, RADAR
418- **Layouts**: LAYOUT_16x9 (10"×5.625"), LAYOUT_16x10, LAYOUT_4x3, LAYOUT_WIDE
419- **Alignment**: "left", "center", "right"
420- **Chart data labels**: "outEnd", "inEnd", "center"
421