pptx-viewer-core

Also published as @christophervr/pptx-viewer -- the two package names are identical releases of the same code. Use whichever name you prefer; they are always published together and kept in sync.

A TypeScript library that reads, creates, edits, and saves PowerPoint (.pptx) files. It runs in the browser and in Node.js, with no native or system dependencies.

Hand it the bytes of a .pptx file and it gives you back a structured, fully typed object that describes every slide: text, shapes, images, charts, tables, and more. Change anything in that object and write it back to a valid .pptx. You can also build new presentations from scratch with a simple chainable API, or turn a deck into Markdown.

There is no UI here: this is the engine on its own. Use it directly when you need to process .pptx files without a screen, for example on a server, in a script, or in a build step. The same engine powers the pptx-react-viewer, pptx-vue-viewer, and pptx-angular-viewer UI components.

📦 npm · 📖 Full docs · ▶️ Live demo · ⚛️ React UI

Install

npm install pptx-viewer-core
# required companions:
npm install jszip fast-xml-parser

Two packages are always needed alongside it: jszip (a .pptx is a ZIP file, and this reads and writes that container) and fast-xml-parser (the slides inside are XML, and this reads and writes it). Password protection and digital signatures need a few extra packages (node-forge, xml-crypto, @xmldom/xmldom), but only if you actually use those features.

What it does

| Capability | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Read | Open a .pptx and pull out slides, text, shapes, images, charts, tables, SmartArt, themes, comments, animations, transitions, and document info | | Edit | Change the data in memory: add, remove, or reorder slides; insert elements; edit text; restyle; switch themes | | Save | Write the changed data back to a valid .pptx, leaving everything you did not touch untouched | | Convert | Turn a deck into Markdown, optionally pulling the images out alongside it | | Export | Save individual slides as their own standalone .pptx files | | Protect | Open and save password-protected files (AES-128/256 encryption) |

Positions and sizes use PowerPoint's own internal unit, the EMU (English Metric Unit): 1 inch = 914,400 EMU, 1 point = 12,700 EMU, and 1 pixel = 9,525 EMU at 96 DPI. You rarely deal with the raw numbers: helpers (inches, cm, mm, pt) let you work in familiar units instead.

Quick start

import { PptxHandler } from 'pptx-viewer-core';

// 1. Open a .pptx file
const handler = new PptxHandler();
const buffer = await fetch('presentation.pptx').then((r) => r.arrayBuffer());
const data = await handler.load(buffer);

console.log(
	`${data.slides.length} slides, canvas ${data.canvasSize.width}×${data.canvasSize.height}`,
);

// 2. Change a slide
data.slides[0].elements[0].text = 'Updated title';

// 3. Save it back to .pptx bytes
const outputBytes = await handler.save(data.slides); // => Uint8Array

// 4. Or pull out just a few slides as separate files
const exports = await handler.exportSlides(data.slides, { slideIndexes: [0, 2] }); // => Map<number, Uint8Array>

load() gives you a PptxData object: a plain, fully typed description of the presentation. Read from it, change it, and pass its slides back to save() to get a valid .pptx file as bytes.

Build a presentation from scratch

The chainable API lets you create a deck step by step, without touching any file format details:

import { Presentation, ThemePresets, ChartBuilder } from 'pptx-viewer-core';

const pptx = await Presentation.create({
	title: 'Sales Report',
	theme: ThemePresets.MODERN_BLUE,
});

// Each slide is added to the deck automatically: no manual .build() or .push() needed
pptx
	.addSlide('Title Slide')
	.addText('Q4 Sales Report', { fontSize: 44, bold: true, x: 100, y: 200, width: 800, height: 80 });

pptx
	.addSlide('Blank')
	.addText('Revenue by Region', { fontSize: 28, x: 50, y: 30, width: 600, height: 50 })
	.addBuilderElement(
		ChartBuilder.create('bar')
			.categories(['North', 'South', 'East', 'West'])
			.addSeries('2026', [210, 150, 180, 120], '#2563EB')
			.title('Revenue ($M)')
			.bounds(50, 100, 860, 420),
	);

pptx.replaceText('2026', 'FY2026'); // find/replace, merge, and templates all chain the same way

const bytes = await pptx.save();

The builder API comes in three levels, from highest to lowest:

1. Presentation: the whole deck at once (slides, text operations, sections, templates, merging, saving).
2. Element builders: one per element type, for fine-grained control: TextBuilder, ShapeBuilder, ChartBuilder, TableBuilder, ImageBuilder, ConnectorBuilder, MediaBuilder, GroupBuilder.
3. PptxXmlBuilder: raw XML, for the rare cases the higher levels do not cover.

It also ships unit helpers (inches, cm, mm, pt), common slide sizes (SlideSizes), and 8 ready-made themes (ThemePresets). The full docs cover every builder.

Turn a deck into Markdown

import { PptxMarkdownConverter } from 'pptx-viewer-core';

const converter = new PptxMarkdownConverter({ includeMetadata: true, imageHandling: 'extract' });
const result = await converter.convert(
	buffer,
	{ outputPath: 'output.md', mediaFolderName: 'media' },
	fileSystemAdapter,
);
// => the Markdown text, plus stats on any images that were pulled out

To write files to disk, pass a FileSystemAdapter (an object with writeFile, writeBinaryFile, and createFolder methods); this keeps the converter free of any assumptions about where it runs. By default it keeps each element where it sat on the slide (absolutely positioned HTML); set semanticMode: true to get clean headings, paragraphs, and lists instead.

PptxHandler API

PptxHandler is the one class you use to open, change, and save files. Its main methods:

| Method | Signature | What it does | | -------------------------- | ------------------------------------------------------- | ------------------------------------------------------ | | load | (data, options?) => Promise<PptxData> | Open a .pptx and return the structured data | | save | (slides, options?) => Promise<Uint8Array> | Write slides back to .pptx bytes | | exportSlides | (slides, options) => Promise<Map<number, Uint8Array>> | Save chosen slides as standalone files | | getImageData | (path) => Promise<string \| undefined> | Get an embedded image as a base64 data URL | | getMediaArrayBuffer | (path) => Promise<ArrayBuffer \| undefined> | Get the raw bytes of an embedded media file | | getLayoutOptions | () => PptxLayoutOption[] | List the slide layouts available | | getCompatibilityWarnings | () => PptxCompatibilityWarning[] | List features in the file that are not fully supported | | applyTheme | (colors, fonts, name?) => Promise<void> | Apply a complete theme | | setPresentationTheme | (path, applyToAll?) => Promise<void> | Load a .thmx theme file |

The PptxData you get from load() exposes slides, canvasSize, theme, slideMasters, slideLayouts, sections, coreProperties, embeddedFonts, and more. See the full docs for the complete PptxHandler, chart/SmartArt, and theme APIs.

What's supported

| Category | Details | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Element types | 16: text, shape, connector, image, picture, table, chart, smartArt, ole, media, group, ink, contentPart, zoom, model3d, unknown | | Preset shapes | 187+ PowerPoint shapes, including ones with adjustable handles | | Chart types | 23, including waterfall, funnel, treemap, sunburst, box-whisker, region-map, and combo charts; with trendlines, error bars, and embedded Excel data | | Transitions | 42 types (including morph, vortex, ripple, and shred) | | Animations | 40+ presets, including colour animation, motion paths, and text that builds in by word, letter, or paragraph | | SmartArt | 13 layout types, broken down into editable shapes | | Fills | Solid, gradient (linear, radial, path), image, and 48 patterns | | Themes | 8 built-in presets, switchable at runtime, with layout and placeholder remapping | | Security | AES-128/256 encryption and decryption, modify-password (SHA), and detection of digital signatures | | Preserved | VBA macros, custom XML, comment authors, and strict-format files are kept intact through a save |

How it works

You only ever work with one class, PptxHandler, and one data object, PptxData. The engine takes care of the rest: when you call load() it unzips the file, reads the XML, resolves the theme, masters, and layouts, and hands you a clean object. save() runs those same steps in reverse.

A few things worth knowing as you use it:

• Every element has a type field (text, shape, image, chart, table, and so on). Check it before reading element-specific properties, for example if (element.type === 'image'). TypeScript then knows exactly which fields exist.
• Shapes are drawn from a built-in catalogue of 187+ PowerPoint shapes, so curves, arrows, and callouts come out with the right outlines.
• Colours follow PowerPoint's theme rules, so a colour defined as "accent 1, but 20% lighter" resolves to the correct final value for the active theme.

Under the hood the engine is split into many small, focused modules. If you want the full load and save pipeline, the complete type system, and a module-by-module map, see the full documentation.

Limitations

• OLE objects (embedded Word docs, spreadsheets, and similar) are read-only: you get their preview image, not their contents.
• SmartArt is broken into editable shapes using the drawing data PowerPoint already saved in the file. There is no engine that re-flows the layout if you change it.
• Chart editing is data-only: you can change series, data points, categories, and the chart type. Other chart properties are read for display but cannot be edited.
• Strict-format files (ISO/IEC 29500 Strict) are converted to the more common Transitional form when opened and converted back when saved.

See the full docs for the details behind each of these.

License

Apache-2.0. Please keep the NOTICE file with redistributions.