pptx-renderer

A high-fidelity, browser-native PPTX renderer that parses Office Open XML (.pptx) files and renders slides as HTML/SVG DOM.

Supports shapes, text, images, tables, charts, SmartArt, groups, backgrounds, gradients, pattern fills, and the full OOXML color pipeline — covering the vast majority of real-world PowerPoint content.

Rendering Example

A complex slide with charts, text styles, shapes, and SmartArt — PowerPoint ground truth vs browser-rendered output:

PowerPoint (Ground Truth)	pptx-renderer (Browser)

Visual Regression Testing

Every rendering capability is automatically verified against PowerPoint output. 452+ visual regression cases with zero failures — covering 187+ preset shapes, 134+ SmartArt layouts, 36+ fill/stroke/gradient variants, and 100 python-pptx cases (text, shape adjustments, composites, charts).

^{E2E evaluation dashboard: side-by-side ground truth vs rendered output with SSIM, color histogram, and IoU metrics per slide.}

Ground truth data (PPTX + PDF pairs) is not committed to the repository due to file size. It can be regenerated locally via scripts/one_shot_full_ground_truth.py with Microsoft PowerPoint installed (macOS and Windows both supported) — see docs/TESTING.md for details.

Install

npm install @aiden0z/pptx-renderer
# or
pnpm add @aiden0z/pptx-renderer

Requires Node.js 20+ for development. Runtime is browser-only.

Quick Start

import { PptxViewer } from '@aiden0z/pptx-renderer';

const container = document.getElementById('pptx-container')!;
const resp = await fetch('/slides/demo.pptx');

// One-liner: parse, build model, and render
const viewer = await PptxViewer.open(await resp.arrayBuffer(), container, {
  listOptions: { windowed: true },
});

Or with more control over each step:

import { PptxViewer, parseZip, buildPresentation } from '@aiden0z/pptx-renderer';

const container = document.getElementById('pptx-container')!;
const viewer = new PptxViewer(container, { fitMode: 'contain' });

const files = await parseZip(arrayBuffer);
const presentation = buildPresentation(files);
viewer.load(presentation);
await viewer.renderList({ windowed: true, batchSize: 8 });

API

PptxViewer (primary, extends EventTarget)

PptxViewer.open(input, container, options?) — Static Factory

Parse, build, and render in one call. Returns a Promise<PptxViewer>.

const viewer = await PptxViewer.open(buffer, container, {
  renderMode: 'list', // 'list' (default) | 'slide'
  listOptions: { windowed: true, batchSize: 8 },
  signal: abortController.signal, // optional AbortSignal
  // ...ViewerOptions
});

new PptxViewer(container, options?)

Option	Type	Default	Description
width	number	--	Container width hint (omit for auto-detect)
fitMode	'contain' | 'none'	'contain'	Responsive fit or fixed size
zoomPercent	number	100	Zoom level (10–400)
scrollContainer	HTMLElement	--	Scroll container for IntersectionObserver root
zipLimits	ZipParseLimits	--	Security limits for ZIP parsing (used by .open())
onSlideChange	(index) => void	--	Shorthand for slidechange event
onSlideRendered	(index, element) => void	--	Shorthand for sliderendered event
onSlideError	(index, error) => void	--	Shorthand for slideerror event
onSlideUnmounted	(index) => void	--	Shorthand for slideunmounted event
onNodeError	(nodeId, error) => void	--	Shorthand for nodeerror event
onRenderStart	() => void	--	Shorthand for renderstart event
onRenderComplete	() => void	--	Shorthand for rendercomplete event

All shorthand callbacks are also available as EventTarget events (e.g. viewer.addEventListener('slidechange', ...)).

Instance Methods

viewer.load(presentation);                              // Load a PresentationData model (no render)
await viewer.renderList({ windowed: true });             // Render all slides in scrollable list
await viewer.renderSlide(0);                             // Render a single slide (no built-in nav UI)

// Load from binary input (parse → build → render). Cleans up previous state on re-open.
await viewer.open(buffer, { renderMode: 'list', signal: abortController.signal });

await viewer.goToSlide(index);                           // Jump to slide (0-based), returns Promise<void>
await viewer.goToSlide(index, { behavior: 'instant' }); // Custom ScrollIntoViewOptions (list mode)
await viewer.setZoom(150);                               // Runtime zoom (10–400)
await viewer.setFitMode('none');                         // Switch fit mode

// Render a single slide into an external container (React/Vue integration, thumbnails).
// Returns a SlideHandle; caller owns it and must call handle.dispose() when done.
const handle = viewer.renderSlideToContainer(index, container, scale?);
handle.dispose();                                        // Clean up slide-specific resources

// Query which slides are currently mounted in the DOM
viewer.isSlideMounted(index);   // boolean
viewer.getMountedSlides();      // number[] (sorted)

// Typed event helpers (return `this` for chaining)
viewer.on('slidechange', (e) => console.log(e.detail.index));
viewer.off('slidechange', listener);

viewer.destroy();               // Cleanup blob URLs, observers, and DOM
viewer[Symbol.dispose]();       // TC39 Explicit Resource Management (calls destroy)

ListRenderOptions

Option	Type	Default	Description
windowed	boolean	false	Use IntersectionObserver windowing
batchSize	number	12	Slides per render batch
initialSlides	number	4	Initial slides to mount (windowed)
overscanViewport	number	1.5	Viewport overscan multiplier

Events (PptxViewerEventMap)

viewer.addEventListener('renderstart', () => {
  /* render cycle began */
});
viewer.addEventListener('rendercomplete', () => {
  /* render cycle finished (fires even on error) */
});
viewer.addEventListener('slidechange', (e) => console.log(e.detail.index));
viewer.addEventListener('sliderendered', (e) => console.log(e.detail.index, e.detail.element));
viewer.addEventListener('slideerror', (e) => console.error(e.detail.index, e.detail.error));
viewer.addEventListener('slideunmounted', (e) => console.log(e.detail.index));
viewer.addEventListener('nodeerror', (e) => console.warn(e.detail.nodeId, e.detail.error));

slidechange fires both on goToSlide() navigation and after each render cycle (initial render included). renderstart/rendercomplete bracket every render cycle (renderList, renderSlide, setZoom, setFitMode).

Instance Properties (read-only)

viewer.presentationData; // PresentationData | null — the parsed model, null before load()
viewer.slideCount; // number — total slides (0 if not loaded)
viewer.slideWidth; // number — intrinsic slide width in px
viewer.slideHeight; // number — intrinsic slide height in px
viewer.currentSlideIndex; // number — currently active slide (0-based)
viewer.isRendering; // boolean — true between renderstart and rendercomplete
viewer.zoomPercent; // number — current zoom level (e.g. 100, 200)
viewer.fitMode; // FitMode — current fit mode ('contain' | 'none')

PptxRenderer (deprecated v1 compat)

PptxRenderer extends PptxViewer and provides the legacy preview(input) API with built-in nav buttons in slide mode. Migrate to PptxViewer for new code.

import { PptxRenderer } from '@aiden0z/pptx-renderer';

const renderer = new PptxRenderer(container, { mode: 'list', listMountStrategy: 'windowed' });
await renderer.preview(buffer); // deprecated — use PptxViewer.open() instead

Utility Exports

import { parseZip, buildPresentation, serializePresentation } from '@aiden0z/pptx-renderer';

const files = await parseZip(arrayBuffer); // PptxFiles
const presentation = buildPresentation(files); // PresentationData
const json = serializePresentation(presentation); // SerializedPresentation (JSON-safe)

Headless Slide Rendering

For advanced use cases (server-side screenshot, custom rendering pipeline):

import { renderSlide } from '@aiden0z/pptx-renderer';
import type { SlideHandle } from '@aiden0z/pptx-renderer';

const handle = renderSlide(presentation, presentation.slides[0], {
  onNodeError: (nodeId, err) => console.warn(nodeId, err),
  mediaUrlCache: new Map(), // optional shared cache for blob URLs
});
document.body.appendChild(handle.element);

// Clean up when done (disposes charts + blob URLs in standalone mode)
handle.dispose();

Model Types

All model types are exported for consumers building custom tooling:

import type {
  PresentationData,
  SlideData,
  SlideNode,
  ThemeData,
  BaseNodeData,
  ShapeNodeData,
  PicNodeData,
  TableNodeData,
  GroupNodeData,
  ChartNodeData,
  TextBody,
  TextParagraph,
  TextRun,
  Position,
  Size,
  NodeType,
  SerializedPresentation,
  SerializedSlide,
  SerializedNode,
  PptxFiles,
  ZipParseLimits,
  FitMode,
  PreviewInput,
  ViewerOptions,
  ListRenderOptions,
  PptxViewerEventMap,
  SlideHandle,
} from '@aiden0z/pptx-renderer';

Rendering Capabilities

Shapes — 187+ Presets + Custom Geometry

All commonly used OOXML DrawingML preset shapes, organized by category:

Category	Count	Highlights
Basic & Geometric	70	Rectangles, ovals, polygons, stars, arcs, clouds, gears, etc.
Flowchart	30	All standard flowchart shapes
Arrows	22	Directional, bent, curved, striped, chevron
Stars & Banners	17	N-point stars, explosions, ribbons, scrolls
Callouts	17	Rectangular, rounded, oval, cloud, line callout variants
Connectors	12	Straight, bent, curved (2-5 segments)
Action Buttons	9	Multi-path 3D with darken/lighten face modifiers
Math & Brackets	12	Plus, minus, multiply, division, brackets, braces
Multi-path 3D	33+	Bevel, cube, can, ribbons — multi-layer SVG with 3D appearance

Custom geometry (<a:custGeom>) is also supported via a general-purpose OOXML path interpreter.

Text — 7-Level Style Inheritance

Full OOXML text cascade: master → layout → shape → paragraph → run. Supports theme fonts, numbered/symbol/picture bullets, multi-level indent, vertical text, superscript/subscript, hyperlinks, and per-shape text insets.

Charts via ECharts

Bar/Column, Line, Area, Pie, Doughnut, Radar, Scatter, Bubble, Surface, Stock/Candlestick — each with 2D and 3D variants. Powered by ECharts, with axis labels, legends, data labels, grid lines, series colors from theme, marker symbols, and custom number formats.

Fill, Stroke & Color

• Fills: solid, linear/radial/rectangular gradient, 52+ pattern fills, image (stretch/tile)
• Strokes: 8 dash styles, 5 arrowhead types, compound lines, line joins
• Colors: full OOXML pipeline — schemeClr → colorMap remap → theme lookup → modifiers (lumMod, lumOff, tint, shade, alpha, satMod, etc.). All 6 color spaces supported.

SmartArt, Tables, Images & More

• SmartArt: 134+ layouts via PowerPoint fallback data (embedded EMF/PDF rendered with pdfjs-dist)
• Tables: OOXML table styles, cell merge, border inheritance
• Images: blob URL with crop, stretch/tile, video/audio placeholders
• Groups: coordinate remapping with recursive child rendering
• Backgrounds: slide → layout → master inheritance chain

Architecture

Three-layer pipeline: Parse -> Model -> Render

ArrayBuffer (.pptx)
  -> ZipParser (jszip extraction)
  -> XmlParser (DOMParser + SafeXmlNode null-safe wrapper)
  -> buildPresentation() (assembles slides/layouts/masters/themes with relationship chains)
  -> SlideRenderer (background -> master shapes -> layout shapes -> slide shapes -> DOM)

Key design decisions:

• SafeXmlNode: Null-safe XML traversal — returns empty nodes instead of null, enabling deep chaining without null checks.
• Lazy group parsing: Group children stored as raw XML, parsed during rendering to avoid deep recursion in model layer.
• Error isolation: Per-node try/catch. A failed shape renders as a dashed-red placeholder; the slide continues.
• No external CSS: All styles inline. The library outputs self-contained HTML fragments.
• Blob URL lifecycle: Created for images/media, tracked in mediaUrlCache, revoked on destroy().

Performance

For large decks (50+ slides), use windowed mounting:

const viewer = await PptxViewer.open(buffer, container, {
  listOptions: {
    windowed: true,
    batchSize: 8,
    initialSlides: 4,
    overscanViewport: 1.5,
  },
});

Details: docs/PERFORMANCE.md

Security

• Treat PPTX input as untrusted. Always configure zipLimits in production.
• External hyperlinks are protocol-filtered (no javascript:, data:, etc.).
• Reporting: docs/SECURITY.md

Development

pnpm install
pnpm dev          # Vite dev server
pnpm test         # Unit tests (vitest)
pnpm test:coverage # Coverage report → coverage/
pnpm build        # Production build
pnpm dev:e2e      # Dev server + Python E2E API server
pnpm lint         # ESLint
pnpm typecheck    # tsc --noEmit
pnpm knip         # Dead code / unused exports detection

Dev pages at http://127.0.0.1:5173:

Page	Purpose
/test/pages/index.html	Upload and preview any PPTX
/test/pages/render-slide.html	Single slide at native resolution
/test/pages/e2e-compare.html	Side-by-side PDF vs HTML with SSIM scores
/test/pages/export.html	Model JSON tree viewer

Documentation

Doc	Content
ARCHITECTURE.md	Parse/model/render pipeline design
PERFORMANCE.md	Tuning options and presets
TESTING.md	Unit/E2E strategy, two-layer metric system, visual regression workflow
CONTRIBUTING.md	PR checklist, code quality tools, and workflow
SECURITY.md	Vulnerability reporting

What's Not Yet Supported

3D effects, animations/transitions, equations (OMML), EMF/WMF vector rendering, shadow/reflection/glow effects, combo charts, secondary chart axes, embedded OLE objects, slide notes rendering.

FAQ

Does this run on Node.js? No. Rendering depends on browser DOM APIs.

Why is my PPTX rendering incomplete? OOXML is a vast spec. Please open a compatibility issue with a minimal PPTX sample — the visual regression pipeline makes it straightforward to add coverage for new cases.

How do I render 100+ slide decks efficiently? Use windowed: true in listOptions — it only mounts slides near the viewport.

License

Apache License 2.0. See LICENSE.