Installation

Install the library via npm. Make sure you meet the requirement of having Node.js version 18.0.0 or higher.

npm install node-pptx-templater

System Requirements

• Node.js: >= 18.0.0
• Module system: ES Modules ("type": "module" in package.json)

Quick Start

Get up and running in under 60 seconds with this simple template rendering example.

import { PPTXTemplater } from 'node-pptx-templater';

// Load the source template
const ppt = await PPTXTemplater.load('template.pptx');

// Select slide 1 and execute operations
ppt.useSlide(1);

// Safely replace text placeholders
ppt.replaceText({
  '{{title}}': 'Quarterly Earnings Report',
  '{{date}}': 'May 2026'
});

// Update an interactive bar chart
ppt.updateChart('sales-chart', {
  categories: ['Q1', 'Q2', 'Q3', 'Q4'],
  series: [
    { name: 'Revenue ($M)', values: [120, 145, 170, 210] }
  ]
});

// Save non-corrupted PPTX to disk
await ppt.saveToFile('./output/annual_report.pptx');

Slide Import Engine

The Slide Import engine allows robust deep copying of individual slides from one template into another.

Unlike basic copy implementations, importSlideFrom performs an exhaustive search and deep-copy of all associated relationships, slide layouts, embedded media, and chart workbooks, remapping them into the new presentation's namespace.

Example: Merging Slide Decks

import { PPTXTemplater } from 'node-pptx-templater';

const master = await PPTXTemplater.load('master_template.pptx');
const source = await PPTXTemplater.load('department_results.pptx');

// Deep-copy slide 2 from department_results into master template
await master.importSlideFrom(source, 2);

// Save the combined deck
await master.saveToFile('merged_presentation.pptx');

Navigation Hyperlinks

Link slides internally or attach special navigation actions directly to text runs or vector shapes using our clean API.

Adding Text Navigation Links

Make matching text clickable to jump directly to standard navigation targets (next, previous, first, or last slide).

ppt.addTextNavigationLink({
  slide: 1,
  element: 'Go to Next Slide',
  action: 'next'
});

Adding Shape Navigation Links

Bind custom navigation actions to vector shapes or button graphics inside your template.

ppt.addShapeNavigationLink({
  slide: 1,
  shapeId: 'Back Button',
  action: 'previous'
});

ContentTypesManager

Every single file inside an OpenXML ZIP package must have its type registered inside the centralized manifest [Content_Types].xml.

Our centralized ContentTypesManager replaces standard fragile string replacements with a parsed in-memory node-tree representation of the manifest. Changes are flushed only during the final package writing step to completely eliminate race conditions.

API Reference

// Inside PPTXTemplater lifecycle:
const contentTypes = ppt.contentTypesManager;

// Override registration for new slide XML
contentTypes.addOverride('/ppt/slides/slide3.xml', 'application/vnd.openxmlformats-officedocument.presentationml.slide+xml');

// Default MIME registration
contentTypes.addDefault('webp', 'image/webp');

RelationshipManager

Relationships define how slides link to layouts, masters, charts, and media assets. Standard regex tools corrupt relationship chains if IDs are not fully unique.

The RelationshipManager provides bulletproof remapping and creation of relative relationship paths inside standard .rels files.

Usage Example

const rels = ppt.relationshipManager;

// Add a safe relationship to slides/slide1.xml
const rId = rels.addRelationship(
  'ppt/slides/slide1.xml',
  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image',
  '../media/image10.png'
);
// Returns unique ID (e.g. 'rId5')

PPTXTemplater

The main class exposed by the library to load, select, modify, and save presentation templates.

Properties & Getters

Main Methods

Chart Engine

PowerPoint charts are structured via complex pairings of a Chart XML part and an embedded Excel Worksheet binary containing matching row/column data cells.

Our Chart Engine automatically updates the underlying series formulas, Category axis values, and regenerates both strCache and numCache so Google Slides and LibreOffice display charts instantly without requiring user-refresh triggers.

Updating Chart Data

ppt.updateChart('revenue-chart', {
  categories: ['Q1', 'Q2', 'Q3', 'Q4'],
  series: [
    { name: 'Target', values: [100, 120, 140, 160] },
    { name: 'Actual', values: [105, 118, 145, 172] }
  ]
});

Table Engine

Dynamically scale template tables. The Table Engine lets you replace placeholder rows while fully preserving the styles, fonts, backgrounds, and cell heights of the original template row.

Example Table Feeding

ppt.updateTable('team-roster', [
          ['Name', 'Title', 'Location'],
          ['Elena', 'Lead Designer', 'Milan'],
          ['Keigo', 'Research Engineer', 'Tokyo'],
          ['Tariq', 'Product Manager', 'Cairo']
        ]);

OpenXML Architecture

An inside look at how files are packaged and managed within the PPTX OpenXML structure.

            ┌───────────────────────────────────────────────┐
            │                 PPTXTemplater                 │
            │                  (Public API)                 │
            └────────┬──────────────────────────────┬───────┘
                     │                              │
            ┌────────▼────────┐            ┌────────▼────────┐
            │   SlideManager  │            │   ChartManager  │
            │  (discovery &   │            │   (Excel & cache│
            │   slide CRUD)   │            │    synchronizer)│
            └────────┬────────┘            └────────┬────────┘
                     │                              │
            ┌────────▼──────────────────────────────▼────────┐
            │                 XMLParser                     │
            │         (fast-xml-parser parsing tree)         │
            └────────┬──────────────────────────────┬───────┘
                     │                              │
            ┌────────▼────────┐            ┌────────▼────────┐
            │ ContentTypesMgr │            │ RelationshipMgr │
            │ (Overrides list)│            │ (.rels mapper)  │
            └────────┬────────┘            └────────┬────────┘
                     │                              │
            ┌────────▼──────────────────────────────▼────────┐
            │                 ZipManager                    │
            │            (JSZip raw serialization)          │
            └───────────────────────────────────────────────┘
          

Troubleshooting

My presentation shows "PowerPoint found a problem with content..."

This is commonly caused by out-of-sync slide count metadata in docProps/app.xml or an override registration missing from [Content_Types].xml.

My placeholders aren't replacing!

PowerPoint split-runs break placeholders like {{placeholder}} into multiple separate <a:t> tags. Enable logging output to identify where fragmentation occurs:

PPTX_LOG_LEVEL=debug node script.js