# dom-to-pptx **The High-Fidelity HTML to PowerPoint Converter (v2.0.3)** [![npm version](https://img.shields.io/npm/v/dom-to-pptx.svg?style=flat-square)](https://www.npmjs.com/package/dom-to-pptx) [![npm downloads](https://img.shields.io/npm/dm/dom-to-pptx.svg?style=flat-square)](https://www.npmjs.com/package/dom-to-pptx) [![](https://data.jsdelivr.com/v1/package/npm/dom-to-pptx/badge?style=rounded)](https://www.jsdelivr.com/package/npm/dom-to-pptx) [![license](https://img.shields.io/npm/l/dom-to-pptx.svg?style=flat-square)](https://github.com/atharva9167j/dom-to-pptx/blob/master/LICENSE) > Trusted by **230,000+ downloads every month** — and now with native motion support. > [!TIP] > **Quick Start for AI Agents (Claude Code, Gemini, Windsurf):** > Run `npx dom-to-pptx-skills` to automatically install professional PPT creation skills into your agent's toolkit. > [!IMPORTANT] > **Experience the Power of dom-to-pptx:** Check out **[Preso AI](https://preso-ai.vercel.app)** — an AI-native presentation platform that uses this library to deliver professional, high-fidelity PowerPoint exports from simple text prompts. --- Most HTML-to-PPTX libraries fail when faced with modern web design. They break on gradients, misalign text, ignore rounded corners, or simply take a screenshot (which isn't editable). **dom-to-pptx** is different. It is a **Coordinate Scraper & Style Engine** that traverses your DOM, calculates the exact computed styles of every element (Flexbox/Grid positions, complex gradients, shadows), and mathematically maps them to native PowerPoint shapes and text boxes. The result is a fully editable, vector-sharp presentation that looks exactly like your web view and as of v2.0.0, one that moves like a real motion-designed deck too. ## 🎬 What's New in v2 This is the biggest release yet, bringing native motion to your exports: - **20+ Element Animations**: Entrance and exit animations — including `fade-in`, `zoom-in`, `fly-in`, and `wipe-in` with directional variants (e.g. `to-up`) — applied directly as CSS classes and baked into real PowerPoint animation effects on export. - **70+ Slide Transitions**: A full library of slide-to-slide transitions, from subtle corporate styles (`slide-transition-fade`, `slide-transition-push`, `slide-transition-wipe`) to expressive creative styles (gallery, doors, zoom, bounce, and more). - **Animation Timing & Sequencing Controls**: Fine-grained `animate-duration-[MS]` and `animate-delay-[MS]` utility classes, plus trigger classes (`animate-trigger-on-click`, `animate-trigger-with`, `animate-trigger-after`) to choreograph click-driven or sequential builds. - **Creative Text Builds**: Character-by-character typing effects (`letter` class) and row-by-row bullet reveals (`paragraph` class). - **Browser Preview Support**: New `animations.css` stylesheet and a `domToPptx.applyBrowserAnimations()` helper to preview element animations in-browser before export (note: slide-to-slide transitions are not previewed in-browser, only element animations are, though both export correctly). See [Animations & Transitions](#-animations--transitions-new-in-v200) below for full usage details. ## Features ### 🎬 Animations & Transitions (New in v2) - **Native Entrance & Exit Animations:** Apply animation classes directly to HTML elements — no JS config needed — and they're converted into real, editable PowerPoint animation effects. - **Slide Transitions:** Apply transition classes to your `.slide` containers to control how PowerPoint moves between slides, from subtle fades to expressive creative effects. - **Sequencing & Triggers:** Coordinate multi-element builds with `animate-trigger-with` (simultaneous) and `animate-trigger-after` (chained), or require a click with `animate-trigger-on-click`. - **Typing & List-Reveal Builds:** Use the `letter` or `paragraph` class for character-by-character or line-by-line text reveals. ### 🚀 Smart Font Embedding (v1.1) - **Smart Font Embedding:** The library **automatically detects** the fonts used in your HTML, finds their URLs in your CSS, and embeds them into the PPTX. Your slides will look identical on any computer, even if the user doesn't have the fonts installed. - **Enhanced Icon Support:** Flawless rendering of FontAwesome, Material Icons, and SVG-based icon libraries (including gradient text icons). ### 🎨 Advanced Visual Fidelity - **Complex Gradients:** Includes a built-in CSS Gradient Parser that converts `linear-gradient` strings (with multiple stops, specific angles like `45deg`, and transparency) into vector SVGs. - **Mathematically Accurate Shadows:** Converts CSS Cartesian shadows (`x`, `y`, `blur`) into PowerPoint's Polar coordinate system (`angle`, `distance`) for 1:1 depth matching. - **Anti-Halo Image Processing:** Uses off-screen HTML5 Canvas with `source-in` composite masking to render rounded images without the ugly white "halo" artifacts found in other libraries. - **Soft Edges/Blurs:** Accurately translates CSS `filter: blur()` into PowerPoint's soft-edge effects, preserving visual depth. ### 📐 Smart Layout & Typography - **Auto-Scaling Engine:** Build your slide in HTML at **1920x1080** (or any aspect ratio). The library automatically calculates the scaling factor to fit it perfectly into a standard 16:9 PowerPoint slide. - **Rich Text Blocks:** Handles mixed-style text (e.g., **bold** spans inside a normal paragraph). - **Text Transformations:** Supports CSS `text-transform: uppercase/lowercase` and `letter-spacing`. ### ⚡ Technical Capabilities - **Z-Index Handling:** Respects DOM order for correct layering of elements. - **Border Radius Math:** Calculates perfect corner rounding percentages based on element dimensions. - **Client-Side:** Runs entirely in the browser. No server required. ## ✨ Featured Project: Preso AI **[Preso AI](https://preso-ai.vercel.app)** is a state-of-the-art AI presentation builder built entirely on top of the `dom-to-pptx` engine. It demonstrates the full potential of this library by transforming AI-generated content into premium, editable PowerPoint decks. - **AI-to-PPTX Workflow**: Turn a single prompt into a 10+ slide high-fidelity presentation. - **Atmospheric UI**: Implements the "Atmospheric UI" design system natively. - **Pixel-Perfect Exports**: Uses `dom-to-pptx` to ensure every gradient, shadow, and layout is preserved in the final `.pptx` file. > **Try it now:** [preso-ai.vercel.app](https://preso-ai.vercel.app) ## Installation ```bash npm install dom-to-pptx ``` ## 🖥️ Command Line Interface (CLI) & Agent Skills (New!) `dom-to-pptx` ships with a CLI suite to run headless PPTX exports or configure AI coding assistants: ### 1. Unified CLI Router (`dom-to-pptx`) Run the unified command directly: ```bash # General help npx dom-to-pptx --help # Run headless exporter (delegates to dom-to-pptx-exporter) npx dom-to-pptx export slides.html [options] # Run interactive skills installer (delegates to dom-to-pptx-skills) npx dom-to-pptx skills ``` ### 2. Headless Exporter CLI (`dom-to-pptx-exporter`) A dedicated command to export local HTML files or remote URLs to PPTX files directly from the command line using a headless browser: ```bash npx dom-to-pptx-exporter slides.html --output presentation.pptx ``` **Options:** - `--output, -o `: Output `.pptx` file path (defaults to same folder as input). - `--selector, -s `: CSS selector for slide container elements (defaults to `.slide`). - `--inject`: Force-inject the local browser bundle (useful if the HTML doesn't bundle `dom-to-pptx`). - `--title ` / `--author `: Add presentation title / author metadata. - `--width ` / `--height `: Set custom slide dimensions in inches. ### 3. Agent Skills Installer CLI (`dom-to-pptx-skills`) An interactive installer to configure presentation engineering skills for coding agents (Claude Code, Gemini CLI, Windsurf, Cursor): ```bash npx dom-to-pptx-skills ``` The installer scans for agent directories, lets you choose targeted locations, and configures the optimized prompt templates automatically. --- ## Usage This library is intended for use in the browser (React, Vue, Svelte, Vanilla JS, etc.). ### 1. Basic Example (Auto-Font Embedding) By default, `dom-to-pptx` attempts to automatically find and embed your web fonts. ```javascript import { exportToPptx } from 'dom-to-pptx'; document.getElementById('export-btn').addEventListener('click', async () => { // Pass the CSS selector of the container await exportToPptx('#slide-container', { fileName: 'slide-presentation.pptx', }); }); ``` ### 2. Manual Font Configuration (Optional) If you are using external fonts (like Google Fonts) that are hosted on a server without CORS headers, automatic detection might fail. In that case, you can explicitly pass the font URLs: ```javascript import { exportToPptx } from 'dom-to-pptx'; await exportToPptx('#slide-container', { fileName: 'report.pptx', // Optional: Only needed if auto-detection fails due to CORS fonts: [ { name: 'Roboto', url: 'https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu4mxK.woff2', }, ], }); ``` ### 3. Multi-Slide Example To export multiple HTML elements as separate slides, pass an array of elements or selectors: ```javascript import { exportToPptx } from 'dom-to-pptx'; document.getElementById('export-btn').addEventListener('click', async () => { const slideElements = document.querySelectorAll('.slide'); await exportToPptx(Array.from(slideElements), { fileName: 'multi-slide-presentation.pptx', }); }); ``` ### 4. SVG Vector Export (Editable Charts) If your HTML contains SVG elements (like charts), you can keep them as vectors for editing in PowerPoint: ```javascript import { exportToPptx } from 'dom-to-pptx'; await exportToPptx('#slide-with-charts', { fileName: 'editable-charts.pptx', svgAsVector: true, // SVGs remain as vectors, not rasterized }); ``` In PowerPoint, right-click the SVG image and select **"Convert to Shape"** (or **Group > Ungroup**) to make it fully editable. ### 5. Animated Slides & Transitions (New in v2.0.0) Animations and transitions are applied declaratively via CSS classes — no extra JavaScript options are needed. Just link the animation stylesheet (note: slide-to-slide transitions are not previewed in the browser; only element animations are) so motion previews correctly in the browser, then export as usual. The `applyBrowserAnimations(parentElement, options)` helper configures the browser-side motion preview timeline. When `enableClick` is `false` (default automatic playback mode), the sequencer automatically schedules the slide's animations step-by-step. It accurately calculates the staggered duration of paragraph and letter builds, ensuring the next click-trigger step does not start until the previous build finishes. When `enableClick` is `true`, it binds a click listener to the `.slide` elements to advance the timeline manually on click. ```html

Dynamic Presentation

Powered by dom-to-pptx native animations

``` **Key animation/transition utility classes:** | Class pattern | Applies to | Purpose | | :------------------------------------------------------------------------------ | :----------------- | :----------------------------------------------------------- | | `fade-in`, `zoom-in`, `fly-in`, `wipe-in` (+ exit variants) | Element | Entrance/exit animation style (20+ available) | | `to-up`, `to-down`, `to-left`, `to-right` | Element | Directional modifier for movement-based animations | | `animate-duration-[MS]` / `animate-delay-[MS]` | Element | Custom timing in milliseconds, e.g. `animate-duration-[600]` | | `animate-trigger-on-click` / `animate-trigger-with` / `animate-trigger-after` | Element | Click-triggered, simultaneous, or sequential-chain timing | | `letter` / `paragraph` | Text element | Character-by-character typing or row-by-row reveal builds | | `slide-transition-fade`, `slide-transition-push`, `slide-transition-wipe`, etc. | `.slide` container | Slide-to-slide transition style (70+ available) | | `transition-duration-fast` / `transition-dur-[MS]` | `.slide` container | Custom transition speed | > For the complete, exhaustive list of all 20+ animations and 70+ transitions with names and previews, see `ANIMATIONS_WHITELIST.md` and `TRANSITIONS_WHITELIST.md` (installed via `npx dom-to-pptx-skills`, or available in the repo's `reference/` directory). ### 6. Browser Usage (Script Tags) You can use `dom-to-pptx` directly via CDN. The bundle includes all dependencies. ```html ``` ## Recommended HTML Structure We recommend building your slide container at **1920x1080px**. The library will handle the downscaling to fit the PowerPoint slide (16:9). ```html
LIVE DATA

Quarterly
Performance

Visualizing the impact of high-fidelity DOM conversion on presentation workflows.

1
Pixel-perfect Shadows
2
Complex Gradients

Revenue Breakdown

Fiscal Year 2024

User 1 User 2
+5

Total Sales

$124,500

+14.5%

Active Users

45.2k

Analysis Summary

The Q3 projection exceeds expectations due to the new optimization algorithm. We observed a 240% increase in processing speed across all nodes.

Confidential
``` ## API ### `exportToPptx(elementOrSelector, options)` Returns: `Promise` - Resolves with the generated PPTX file data (Blob). | Parameter | Type | Description | | :------------------ | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | | `elementOrSelector` | `string` \| `HTMLElement` \| `Array` | The DOM node(s) or ID selector(s) to convert. Can be a single element/selector or an array for multi-slide export. | | `options` | `object` | Configuration object. | **Options Object:** | Key | Type | Default | Description | | :--------------- | :-------- | :-------------- | :------------------------------------------------------------------------------------------------------------ | | `fileName` | `string` | `"export.pptx"` | The name of the downloaded file. | | `autoEmbedFonts` | `boolean` | `true` | Automatically detect and embed used fonts. | | `fonts` | `Array` | `[]` | Manual array of font objects: `{ name, url }`. | | `skipDownload` | `boolean` | `false` | If `true`, the file is not downloaded automatically. Use the returned `Blob` for custom handling (upload). | | `svgAsVector` | `boolean` | `false` | If `true`, keeps SVG elements as vectors (not rasterized). Enables "Convert to Shape" in PowerPoint. | | `layout` | `string` | `"LAYOUT_16x9"` | Slide layout name (e.g., `LAYOUT_4x3`, `LAYOUT_16x10`, `LAYOUT_WIDE`). | | `width` | `number` | `10` | Custom slide width in inches (requires `height` to be set). | | `height` | `number` | `5.625` | Custom slide height in inches (requires `width` to be set). | | `listConfig` | `object` | `undefined` | Global overrides for list styles. Structure: `{ color: string, spacing: { before: number, after: number } }`. | > Note: animations and transitions are controlled entirely through CSS classes on your elements (see [Animated Slides & Transitions](#5-animated-slides--transitions-new-in-v120)), not through the `options` object. **List Configuration Example:** ```javascript listConfig: { spacing: { before: 10, // Space before bullet (pt) after: 5 // Space after bullet (pt) } } ``` ### `applyBrowserAnimations(parentElement, options)` Applies browser animation inline styles by parsing animation class utilities. This helper enables real-time browser previewing of custom slide animation speeds, delays, sequencing triggers, and text builds with PowerPoint-accurate timeline parity. | Parameter | Type | Default | Description | | :-------------- | :------------ | :--------- | :--------------------------------------------------- | | `parentElement` | `HTMLElement` | _Required_ | The root element of the slide stage or presentation. | | `options` | `object` | `{}` | Optional configuration object. | **Options Object (`options`):** | Key | Type | Default | Description | | :------------ | :-------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enableClick` | `boolean` | `false` | If `true`, click-triggered steps are initially paused and advance one-by-one upon slide clicks (matching manual click timing). If `false` (default), click-triggered steps are automatically chained and play sequentially, accurately waiting for staggered paragraph/letter builds to finish. | ## Important Notes 1. **Fonts & CORS:** - **Automatic Embedding:** Works perfectly for local fonts and external fonts served with correct CORS headers. - **Google Fonts:** For auto-detection to work with Google Fonts, you must add `crossorigin="anonymous"` to your link tag: `` - If a font cannot be accessed due to CORS, the library will log a warning and proceed without embedding it (PowerPoint will fallback to Arial). 2. **Layout System:** The library does not "read" Flexbox or Grid definitions directly. It measures the final `x, y, width, height` of every element relative to the slide root and places them absolutely. This ensures 100% visual accuracy regardless of the CSS layout method used. 3. **CORS Images:** External images (`` tags) must also be served with `Access-Control-Allow-Origin: *` headers to be processed by the rounding/masking engine. 4. **Animations & Transitions:** Link `animations.css` and `transitions.css` (note: only slide element animations are previewed in the browser; slide-to-slide transitions are not previewed in-browser, though they are still exported correctly) so motion previews correctly in your browser before export — the export engine reads the applied classes and converts them into native PowerPoint animation/transition effects regardless of whether the stylesheets are present at export time. ## Contributors A huge thank you to everyone who has helped improve `dom-to-pptx`! Please see [CONTRIBUTORS.md](CONTRIBUTORS.md) for the full list of our amazing contributors. ## License MIT © [Atharva Dharmendra Jagtap](https://github.com/atharva9167j) and `dom-to-pptx` contributors. ## Acknowledgements This project is built on top of [PptxGenJS](https://github.com/gitbrent/PptxGenJS). Huge thanks to the PptxGenJS maintainers and all contributors — dom-to-pptx leverages and extends their excellent work on PPTX generation.