@arcsin1/html2pptx

Convert an HTML slide page into an editable PPTX document. It provides browser extraction scripts, normalization, and OOXML writing without depending on Electron.

The converter prioritizes editable PowerPoint objects where the HTML/CSS visual can be represented safely. Source visuals that cannot be mapped reliably stay in the caller-provided raster background rather than becoming misleading native objects.

Install

pnpm add @arcsin1/html2pptx

Usage

import {
  buildHtmlToPptxExtractScript,
  generatePptx,
  normalizeExtractedHtmlToPptxSlide,
} from '@arcsin1/html2pptx'

const rawSlide = await browserRuntime.evaluate(
  buildHtmlToPptxExtractScript({
    pageWidthPx: 1600,
    pageHeightPx: 900
  })
)
const slide = normalizeExtractedHtmlToPptxSlide(rawSlide, 'Overview')

const pptx = generatePptx({
  title: 'Deck',
  author: 'Your Name',
  slides: [slide]
})

pptx is a Uint8Array containing a standards-compliant .pptx Open Packaging Convention ZIP. Save it in a browser, Worker, server, or Electron application. For Node.js file output, import writeHtmlToPptx from @arcsin1/html2pptx/node.

Document metadata, notes, and async export

The title and author of an HtmlToPptxDocument are written into the package docProps/core.xml, so PowerPoint's file properties panel shows them. Application metadata (docProps/app.xml), presProps, viewProps, and tableStyles parts are emitted as well, keeping strict consumers from asking for a repair.

Speaker notes are optional per slide:

const pptx = generatePptx({
  title: 'Deck',
  slides: [{ texts: [], notes: 'Talking points for slide 1' }]
})

Slides that carry notes get a matching ppt/notesSlides/notesSlideN.xml (with a shared notesMaster); slides without notes produce no notes parts.

Slide sizes

The library supports these presentation page sizes:

| Format | Browser page size | PowerPoint page size | | --- | --- | --- | | Widescreen 16:9 | 1600 x 900 px | 13.333333333 x 7.5 in (default) | | Standard 4:3 | 1600 x 1200 px | 10 x 7.5 in |

Use a browser page with the matching aspect ratio. Widescreen is the default. For a 4:3 export, configure your integration to use 10 x 7.5 in for its slide document. The writer recognizes both the exact and display-rounded 13.333 x 7.5 in wide presets and writes PowerPoint's canonical page size.

const slideSize = { widthIn: 10, heightIn: 7.5 }
const pptx = generatePptx({ title: '4:3 deck', slideSize, slides: [slide] })

Supported output

The extractor works from browser-computed layout, not from a limited HTML tag whitelist. The following matrix describes the editable result it can produce.

| Source content | PowerPoint output | | --- | --- | | <h1>-<h6>, <p>, <div>, <span>, <section>, <article>, <header>, <footer>, <aside>, <figure>, and <figcaption> containing visible text | Editable text boxes and text runs | | <ul>, <ol>, and <li> | Editable text boxes with PowerPoint bullets or numbered paragraphs | | Inline semantic text such as <strong>, <b>, <em>, <i>, <u>, <s>, <del>, <small>, <big>, and <mark> | Editable text runs where the corresponding DrawingML formatting exists | | Text formatting | Font family, size, color, bold, italic, underline, strike-through, alignment, line spacing, character spacing, paragraph spacing, vertical alignment, and padding | | CSS font sizes | Scaled with the same page-to-slide geometry as positions and text boxes. For the standard 1600 x 900 px to 13.333333333 x 7.5 in export, a 16px source font becomes 9.6pt so its wrapping and placement match the HTML. | | Common layout containers with solid fills | Editable rectangles, rounded rectangles, ellipses, and lines | | Borders | Solid or dashed borders; individual CSS border sides export as line shapes | | Rotation | Simple rotation is preserved for text, shapes, and images | | <img> | Raster images placed as PowerPoint images | | <svg> and <canvas> | Rasterized PNG/JPEG images placed as PowerPoint images | | Simple CSS background images | A single, no-repeat image with one-to-one sizing and positioning exports as an image | | Simple <table>, <thead>, <tbody>, <tfoot>, <tr>, <th>, and <td> | Editable DrawingML tables with row/column spans, cell fill, borders, alignment, and basic text formatting | | Rich tables | Editable DOM-derived shapes and text instead of a lossy native table conversion | | Paint order | Relative z-order is reconstructed from CSS stacking contexts and browser paint observations | | Slide transition and animations | The OOXML writer accepts transitionType and caller-provided animationTraces |

The extraction result includes extractionReport, which tells the caller when a text, shape, or image limit was reached or when an unsupported transform was encountered. Use it to decide whether to retain a screenshot fallback.

Fonts

The extractor reads the computed CSS font-family and writes it into the Latin, East Asian, and complex-script DrawingML font slots. This preserves the font reference for Latin, CJK, and complex-script text when the font is available on the machine opening the presentation.

For portable output, explicitly embed the licensed font data through embeddedFonts. The library does not inspect browser font usage, scan the operating system, select font variants, or copy fonts automatically; callers should only embed the families and styles actually used by the slide.

const pptx = generatePptx({
  title: 'Deck with fonts',
  slides: [slide],
  embeddedFonts: [
    {
      fontFace: 'Noto Sans SC',
      style: 'regular',
      ttfBuffer: fontPayload
    }
  ]
})

Font files must be licensed for embedding. ttfBuffer must contain a PowerPoint-compatible embedded font payload. Despite the historical property name, the writer stores the supplied bytes unchanged as ppt/fonts/*.fntdata; it does not convert TTF, OTF, WOFF, or WOFF2. For Windows PowerPoint, supply a valid PowerPoint-compatible EOT fontdata payload for every embedded style (for example, regular and bold), rather than raw WOFF/WOFF2 bytes.

If no embeddedFonts are supplied, the PPTX references the extracted font family and PowerPoint resolves it from the machine that opens the file.

Limits and fallbacks

• Complex transforms including skew, 3D transforms, and non-axis-aligned transform chains cannot be reconstructed as editable PowerPoint objects. Set unsupportedTransformStrategy: 'raster-fallback' to keep them in the background image instead of exporting an approximation.
• CSS gradients, masks, clip paths, blend modes, filters, backdrop filters, and complex CSS background layers are not converted to editable PowerPoint formatting. Keep them in a raster base layer.
• Radial gradients, CSS filters, SVG filter effects, video, iframe content, and arbitrary web components do not have native editable output.
• SVG and canvas are preserved visually as raster images, not editable SVG or chart objects.
• Native tables intentionally fall back to DOM text and shapes when cells have nested layout, mixed typography, badges, or row-level paint that a DrawingML table cannot represent accurately.
• Image extraction requires browser-readable image data. Cross-origin images without CORS access may remain only in the screenshot fallback.
• Text, shapes, and images are bounded by maxTextBoxes, maxShapes, maxImages, maxTextChars, and maxImageBytes to keep exports predictable. The limits applied during extraction are echoed back on the extracted slide (limits) and reused by normalizeExtractedHtmlToPptxSlide, so the two stages never disagree on truncation.
• If the text-measurement runtime (@chenglou/pretext) cannot be loaded in the browser context, extraction falls back to element-based text boxes and sets extractionReport.pretextUnavailable = true so callers can detect the degraded path.

License

Apache-2.0