PptxGenJS - Generate PowerPoint Presentations

4.0.1 · active · verified Sun Apr 19

PptxGenJS is a comprehensive JavaScript library designed for programmatically generating professional PowerPoint presentations (PPTX files) directly from various JavaScript environments, including Node.js, React, Angular, Vite, Electron, and modern web browsers. The library is currently at version 4.0.1 and maintains a fairly active release cadence, with minor and patch versions released every few weeks to months. It differentiates itself by allowing the creation of complex slides with text, tables, shapes, images, and charts without requiring a Microsoft PowerPoint installation or license. Key features include defining custom Slide Masters, supporting SVGs, animated GIFs, YouTube embeds, RTL text, and Asian fonts. It also offers a unique HTML to PowerPoint conversion for tables and provides full TypeScript definitions, ensuring a robust development experience. Presentations created are standards-compliant Open Office XML (OOXML) files compatible with major office suites like Microsoft PowerPoint, Apple Keynote, and LibreOffice Impress.

Common errors

```
PowerPoint 'needs repair' message when opening .pptx file.
```
cause This error often indicates malformed XML within the generated PPTX file. Common causes in PptxGenJS have included issues with table auto-paging, especially when combined with hyperlinks, or incorrect property values (e.g., border being a string instead of a number).

fix First, ensure you are on the latest stable version of PptxGenJS (currently 4.0.1 or higher). Review your code for common pitfalls like incorrect data types for properties (e.g., `border` expecting a number `pt` property). If the issue persists, simplify the slide content to isolate the problematic element.
```
Cannot use import statement outside a module (in Node.js) or require is not defined (in browser)
```
cause This is a common module system mismatch error. Node.js environments expecting CommonJS (`require`) will fail with ESM `import` statements without proper configuration, and vice-versa in browser or ESM-only contexts.

fix For Node.js, ensure your `package.json` specifies `"type": "module"` for ESM, or use `const PptxGenJS = require('pptxgenjs');` for CommonJS. For browser environments, if not using a bundler, load `pptxgen.bundle.js` via a `<script>` tag, which exposes `PptxGenJS` globally.
```
TypeError: pptx.writeFile is not a function (or similar file operation error in Node.js)
```
cause In Node.js environments, `writeFile` often returns a Promise, and it might not be directly available or used incorrectly without `await` or `.then()`. Also, browser `writeFile` triggers a download, while Node.js `writeFile` requires a path.

fix Ensure you are awaiting the `writeFile` call in an `async` function (`await pptx.writeFile({ fileName: 'MyPresentation.pptx' });`). Additionally, confirm you are in a Node.js context if expecting server-side file saving, and provide a valid file path. For browser, ensure it's called from a user interaction context to trigger download.

Warnings

breaking Starting with v3.6.0, PptxGenJS dropped explicit support for Internet Explorer 11 in its demo applications. While the library itself may still function with polyfills, official support and testing for IE11 are no longer provided. Users targeting older browsers should consider remaining on v3.5.0 or ensuring comprehensive polyfills.
Fix: For projects requiring IE11 compatibility, consider using PptxGenJS v3.5.0 or earlier, or thoroughly test with polyfills (e.g., core-js) to ensure desired functionality.
deprecated The chart properties `fill` and `border` within `chart` options have been deprecated in favor of `plotArea` in version 3.11.0. While the old properties might still work, it's recommended to update your code to use the new `plotArea` object for chart area styling.
Fix: Replace direct `fill` and `border` properties in chart options with the `plotArea` object, which accepts `fill` and `border` as its own properties. Example: `chart: { plotArea: { fill: 'FFFFFF', border: { pt: 1, color: '000000' } } }`.
gotcha When using table auto-paging and including hyperlinks within table cells, presentations generated with older versions of PptxGenJS (prior to 4.0.1) could sometimes result in 'needs repair' errors when opened in PowerPoint.
Fix: Upgrade to PptxGenJS version 4.0.1 or newer. This issue has been explicitly fixed in version 4.0.1.
gotcha Reusing configuration objects for `defineSlideMaster()` without deep cloning in older versions could lead to unintended modifications across masters or unexpected behavior, as objects might be mutated when used by different master definitions.
Fix: Upgrade to PptxGenJS version 4.0.0 or newer, where this issue was addressed. If upgrading is not an option, ensure that any configuration objects passed to `defineSlideMaster()` are unique or are deep-cloned before reuse to prevent shared state issues.

Install

npm install pptxgenjs npm
yarn add pptxgenjs yarn
pnpm add pptxgenjs pnpm

Imports

PptxGenJS
wrong:
```
const PptxGenJS = require('pptxgenjs')
```
correct:
```
import PptxGenJS from 'pptxgenjs'
```
This is the primary way to import the default export, typically an instance of the PptxGenJS class. While `require` works in CJS, modern Node and browser environments prefer ESM imports.
PptxGenJS, PptxGenJS.Slide, PptxGenJS.Shape
```
import PptxGenJS, { ISlide, IShape } from 'pptxgenjs'
```
When using TypeScript, type definitions are automatically included. You can directly import interfaces like `ISlide` or `IShape` for type hinting. The main class is `PptxGenJS`.
PptxGenJS (global variable)
```
<script src="https://cdn.jsdelivr.net/gh/gitbrent/pptxgenjs/dist/pptxgen.bundle.js"></script>
// Then access via window.PptxGenJS or simply PptxGenJS
```
For browser environments without a module bundler, the CDN-provided `pptxgen.bundle.js` makes `PptxGenJS` available as a global variable.

Quickstart

This quickstart demonstrates how to instantiate PptxGenJS, define a slide master for branding, add a new slide using that master, then insert text and a basic table. Finally, it shows how to trigger a file download in a browser or logs a message for Node.js environments.

import PptxGenJS from 'pptxgenjs';

async function createPresentation() {
  let pptx = new PptxGenJS();
  
  // Define a Slide Master for consistent branding
  pptx.defineSlideMaster({
    title: 'MASTER_TITLE',
    bkgd: 'F1F1F1',
    objects: [
      { rect: { x: 0, y: 0, w: '100%', h: 0.75, fill: { color: 'E6E6E6' } } },
      { text: { text: 'PptxGenJS Demo', options: { x: 0.5, y: 0.25, w: 5, h: 0.5, fontSize: 24 } } },
      { image: { x: 9.5, y: 0.1, w: 0.75, h: 0.75, path: 'https://raw.githubusercontent.com/gitbrent/PptxGenJS/master/docs/assets/images/logo.png' } }
    ]
  });

  let slide = pptx.addSlide({ masterName: 'MASTER_TITLE' });

  slide.addText(
    'Hello PptxGenJS! This is a simple example.',
    { x: 0.5, y: 1.5, w: 12, h: 1, fontSize: 36, color: '363636', align: 'center' }
  );

  slide.addTable([
    [{ text: 'Header 1' }, { text: 'Header 2' }],
    ['Row 1, Cell 1', 'Row 1, Cell 2'],
    ['Row 2, Cell 1', 'Row 2, Cell 2']
  ], {
    x: 1, y: 3,
    w: 10, colW: [5, 5],
    border: { pt: 1, color: 'CCCCCC' },
    fill: 'F9F9F9',
    align: 'center',
    valign: 'middle'
  });

  // In a browser, this will trigger a download
  // In Node.js, you would typically use save() to write to a file system
  if (typeof window !== 'undefined') {
    pptx.writeFile({ fileName: 'MyPresentation.pptx' });
  } else {
    // Node.js example: save to a file
    // await pptx.writeFile({ fileName: 'MyPresentation.pptx' });
    console.log('Presentation generated. Run in browser to download.');
  }
}

createPresentation();

view raw JSON →