pptx-react-renderer

pptx-react-renderer is a browser-first library for parsing .pptx files and rendering them to semantic HTML.

The package is framework-agnostic, but it works naturally in React because the main API renders into a container element you control.

Project Status

pptx-react-renderer is heavily under development.

It is already usable for browser-based slide previewing, but the renderer is not feature-complete and it does not aim to match PowerPoint perfectly yet. Expect rough edges, unsupported constructs, and rendering mismatches on complex decks.

Features

• Parses .pptx archives client-side with jszip
• Renders slides to regular DOM nodes and CSS
• Supports text, images, shapes, tables, and a subset of SmartArt/graphic frames
• Exposes both parse and render APIs
• Ships as ESM and CommonJS with TypeScript types

Install

pnpm add pptx-react-renderer

Quick Start

import { renderPptx } from "pptx-react-renderer";

const response = await fetch("/deck.pptx");
const arrayBuffer = await response.arrayBuffer();

const container = document.getElementById("preview");

if (!container) {
  throw new Error("Missing preview container");
}

await renderPptx(arrayBuffer, {
  container,
  scale: 0.6,
  showSlideNumbers: true,
  theme: "light",
});

React Example

import { useEffect, useRef } from "react";
import { renderPptx } from "pptx-react-renderer";

export function PptxPreview({ file }: { file: ArrayBuffer | null }) {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!file || !ref.current) return;

    void renderPptx(file, {
      container: ref.current,
      scale: 0.7,
      showSlideNumbers: true,
      theme: "light",
    });
  }, [file]);

  return <div ref={ref} />;
}

Playground

This repo also includes a static browser playground under playground/ for drag-and-drop local .pptx rendering. It is designed for GitHub Pages publishing from the gh-pages branch and does not upload presentations to a server.

API

renderPptx(input, options)

Parses a .pptx file and immediately renders the resulting slides into options.container.

input can be an ArrayBuffer or Uint8Array.

parsePptx(input)

Returns a normalized slide model without rendering:

type PptxParseResult = {
  slides: PptxSlide[];
  slideWidth: number;
  slideHeight: number;
  title?: string;
};

input can be an ArrayBuffer or Uint8Array.

renderSlides(slides, options)

Renders a previously parsed slide model into a container.

RenderOptions

type RenderOptions = {
  container: HTMLElement;
  scale?: number;
  showSlideNumbers?: boolean;
  theme?: "light" | "dark";
};

Defaults:

• scale: 1
• showSlideNumbers: true
• theme: "light"

What It Supports

• text boxes with rich text runs and paragraph-level formatting
• images extracted from the PPTX archive and inlined as data URLs
• basic shapes and fills
• tables
• grouped slide content and a subset of graphic frames / SmartArt-like data

This is not a pixel-perfect PowerPoint clone. The goal is pragmatic HTML rendering of common slide content in browser applications.

Current Limitations

• The package is browser-first. Parsing requires DOMParser, FileReader, and Blob, and rendering requires document.
• Server-side rendering is not supported directly. Use the parser and renderer only in browser-like client runtimes.
• Grouped shapes are not fully reconstructed yet. In the current parser, group containers are simplified rather than expanded into their original child elements.
• Chart and table graphicFrame content is currently rendered as placeholder blocks instead of full chart/table fidelity.
• SmartArt and diagram support is partial. The parser attempts to extract diagram data and drawing shapes, but many decks still fall back to simplified node/text rendering.
• Custom geometry support is incomplete. Some path data is handled, but arc commands are currently skipped.
• Missing or unresolved embedded images fall back to a placeholder image box.
• Theme support is intentionally minimal and limited to the library's light/dark wrapper styling.
• Large decks can use significant memory because image assets are converted to data URLs during parsing.

Runtime Notes

• Parsing requires browser APIs: DOMParser, FileReader, and Blob.
• Rendering additionally requires document.
• Server-side rendering is not supported directly.
• The published package currently targets Node.js 20+ for local development, testing, and build tooling.
• For React or Next.js apps, call the renderer from client-only code such as useEffect in a client component.
• If you run tests in Node, use a DOM-capable environment such as jsdom.
• Image data is currently inlined as data URLs during parsing, which can increase memory usage for large decks.

Package Format

• ESM and CommonJS builds are published.
• TypeScript declarations are included.
• The package exports named exports only.

Development

pnpm install
pnpm run fixtures:generate
pnpm run verify
pnpm run pack:check
pnpm run test:browser
pnpm run test:visual

Use Node.js 20 or newer for local development. The current Vitest/Vite toolchain in this repo does not support Node 18.

To regenerate the committed sanitized golden fixture from a local source deck:

PPTX_COMPLEX_SOURCE="/absolute/path/to/source-deck.pptx" pnpm run fixtures:sanitize-complex

The sanitized fixture preserves slide structure, SmartArt/diagram XML, tables, groups, relationships, and media slots while replacing sensitive text, metadata, and image payloads.

Versioning And Releases

• Follow semver.
• Merges to main are the release trigger.
• Every pull request must carry exactly one release label: release:patch, release:minor, release:major, or release:skip.
• The publish workflow reads the merged PR label, resolves the next version, publishes to npm, and creates a matching GitHub release tag.
• Before 1.0.0, release labels are intentionally softened:
  • release:major becomes a semver minor bump, for example 0.2.3 -> 0.3.0
  • release:minor becomes a semver patch bump, for example 0.2.3 -> 0.2.4
  • release:patch stays a patch bump
  • release:skip suppresses publication for that merge
• npm trusted publishing is configured for OpenRenderKit/pptx-react-renderer and .github/workflows/publish.yml.
• The package is currently published as pptx-react-renderer@0.1.1.
• main is intended to stay releasable; use branches and pull requests for normal changes.
• Release tags matching v* are protected against rewrites and deletions.

See docs/RELEASING.md for the concrete release flow and recovery steps.

Testing Strategy

• unit and parser/renderer regression tests run in vitest with jsdom
• committed .pptx fixtures under test/fixtures/real/ cover realistic parse and render paths
• a Playwright smoke test renders a real fixture in Chromium against the built package
• a case-based visual-regression path renders real PPTX fixtures through LibreOffice, screenshots selected slides from the browser renderer, and diffs them with pixelmatch
• a sanitized golden deck derived from a complex local source presentation is committed so CI can exercise realistic SmartArt, tables, groups, and mixed media without depending on private files
• a committed Slop-Sample deck compares every slide in CI, including theme styling, placeholder text, notes-safe content, tables, images, and diagram-heavy layouts

pnpm run test:visual requires LibreOffice (soffice) and Poppler (pdftoppm) locally. CI runs the visual suite on every change and publishes metrics, diff images, and an HTML side-by-side report artifact, but it does not block routine 0.x or x.y.z work. On pull requests, CI also compares the current branch renderer output against the latest successful main visual artifact, posts a PR comment with ranked renderer changes plus regressed/improved fidelity sections, and publishes preview reports to GitHub Pages so the comment can link to stable browser-viewable outputs and embed top changed slide previews when there are non-zero deltas. Hard threshold enforcement remains available locally and for future major-release gates. See docs/TESTING.md for the visual-regression model, local prerequisites, and GitHub Actions behavior.

Contributing

See CONTRIBUTING.md for local setup, verification, and release steps.

Security

See SECURITY.md for vulnerability reporting guidance.