dom-to-pptx

The High-Fidelity HTML to PowerPoint Converter (v1.0.6).

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.

Features

🎨 Advanced Visual Fidelity

• Complex Gradients: Includes a built-in CSS Gradient Parser that converts linear-gradient strings (with multiple stops, angles, and transparency) into vector SVGs for perfect rendering. This now also supports text-fill-color gradients, falling back to the first color for broad compatibility.
• 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 (10 x 5.625 inches) with auto-centering.
• Rich Text Blocks: Handles mixed-style text (e.g., bold spans inside a normal paragraph) while sanitizing HTML source code whitespace (newlines/tabs) to prevent jagged text alignment.
• Font Stack Normalization: Automatically maps web-only fonts (like ui-sans-serif, system-ui) to safe system fonts (Arial, Calibri) to ensure the file opens correctly on any computer.
• Text Transformations: Supports CSS text-transform: uppercase/lowercase and letter-spacing (converted to PT).

⚡ 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.

Installation

npm install dom-to-pptx

Usage

This library is intended for use in the browser (React, Vue, Svelte, Vanilla JS, etc.).

1. Basic Example

import { exportToPptx } from 'dom-to-pptx';

// Note: If you are using a module bundler, it is recommended to import pptxgenjs
// directly into your project to ensure tree-shaking and optimal bundle size.
// import PptxGenJS from 'pptxgenjs'; // Uncomment and use if needed for your setup

document.getElementById('download-btn').addEventListener('click', async () => {
  // Pass the CSS selector of the container you want to turn into a slide
  await exportToPptx('#slide-container', {
    fileName: 'slide-presentation.pptx',
  });
});

2. Multi-Slide Example

To export multiple HTML elements as separate slides, pass an array of elements or selectors:

import { exportToPptx } from 'dom-to-pptx'; // ESM or CJS import

document.getElementById('export-btn').addEventListener('click', async () => {
  const slideElements = document.querySelectorAll('.slide');
  await exportToPptx(Array.from(slideElements), {
    fileName: 'multi-slide-presentation.pptx',
  });
});

3. Browser Usage (single-file bundle or legacy setup)

You can use dom-to-pptx directly in the browser in two ways:

• Recommended — Single-file bundle (includes runtime deps):

<!-- Single script that contains dom-to-pptx + pptxgenjs + html2canvas -->
<script src="/node_modules/dom-to-pptx/dist/dom-to-pptx.bundle.js"></script>
<script>
  document.getElementById('download-btn').addEventListener('click', async () => {
    // The library is available globally as `domToPptx`
    await domToPptx.exportToPptx('#slide-container', { fileName: 'slide-presentation.pptx' });
  });
</script>

You can also load the bundle from a CDN (unpkg/jsdelivr):

<script src="https://unpkg.com/dom-to-pptx@latest/dist/dom-to-pptx.bundle.js"></script>

• Legacy — Explicit runtime includes (smaller dom-to-pptx file, you manage deps):

<!-- Load pptxgenjs first -->
<script src="https://cdn.jsdelivr.net/npm/pptxgenjs@latest/dist/pptxgen.bundle.js"></script>
<!-- html2canvas is required by the legacy dom-to-pptx build for backdrop-filter and canvas image processing -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/html2canvas.min.js"></script>
<!-- Then load the legacy dom-to-pptx file that expects the above libs -->
<script src="/node_modules/dom-to-pptx/dist/dom-to-pptx.min.js"></script>
<script>
  document.getElementById('download-btn').addEventListener('click', async () => {
    await domToPptx.exportToPptx('#slide-container', { fileName: 'slide-presentation.pptx' });
  });
</script>

Notes:

• The standalone dist/dom-to-pptx.bundle.js includes pptxgenjs and html2canvas, so you only need one script tag.
• If you prefer a smaller payload and already have pptxgenjs on the page, use the legacy dist/dom-to-pptx.min.js and load pptxgenjs first.

4. Recommended HTML Structure

Recommended HTML Structure

For the best results, treat your container as a fixed-size canvas. We recommend building your slide at 1920x1080px. The library will handle the downscaling.

<!-- Container (16:9 Aspect Ratio) -->
<!-- The library will capture this background color/gradient automatically -->
<div
  id="slide-container"
  class="slide w-[1000px] h-[562px] bg-white mx-auto shadow-xl relative overflow-hidden rounded-lg flex items-center justify-center p-10"
>
  <div
    class="w-full max-w-3xl bg-white rounded-2xl shadow-xl overflow-hidden grid md:grid-cols-2 items-center 
border-l-2 border-indigo-500"
  >
    <div class="p-12">
      <h2 class="text-xl font-semibold text-indigo-500 uppercase tracking-wide mb-2">
        Core Concept
      </h2>
      <h3 class="text-4xl font-bold text-slate-800 mb-6">From Bit to Qubit</h3>
      <div class="space-y-6 text-slate-600">
        <div class="flex items-start gap-4">
          <div
            class="flex-shrink-0 w-8 h-8 bg-slate-200 rounded-full flex items-center justify-center font-bold text-slate-700"
          >
            B
          </div>
          <div>
            <h4 class="font-bold text-slate-700">Classical Bit</h4>
            <p>
              A fundamental unit of information that is either
              <span class="font-semibold text-indigo-600">0</span> or
              <span class="font-semibold text-indigo-600">1</span>.
            </p>
          </div>
        </div>
        <div class="flex items-start gap-4">
          <div
            class="flex-shrink-0 w-8 h-8 bg-indigo-200 rounded-full flex items-center justify-center font-bold text-indigo-700"
          >
            Q
          </div>
          <div>
            <h4 class="font-bold text-slate-700">Quantum Bit (Qubit)</h4>
            <p>
              Can be <span class="font-semibold text-indigo-600">0</span>,
              <span class="font-semibold text-indigo-600">1</span>, or a
              <span class="font-semibold text-indigo-600">superposition</span>
              of both states simultaneously.
            </p>
          </div>
        </div>
      </div>
    </div>
    <div class="h-64 md:h-full">
      <img
        src="https://picsum.photos/800/600?random=2"
        alt="Stylized representation of a qubit"
        class="w-full h-full object-cover"
      />
    </div>
  </div>
</div>

API

exportToPptx(elementOrSelector, options)

| Parameter | Type | Description | | :------------------ | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | | elementOrSelector | string | HTMLElement | Array<string \| HTMLElement> | 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 | "slide.pptx" | The name of the downloaded file. | | backgroundColor | string | null | Force a background color for the slide (hex). |

Important Notes

1. CORS Images: Because this library uses HTML5 Canvas to process rounded images, any external images must be served with Access-Control-Allow-Origin: * headers. If an image is "tainted" (CORS blocked), the browser will refuse to read its data, and it may appear blank in the PPTX.
2. Layout System: The library does not "read" Flexbox or Grid definitions directly. Instead, it lets the browser render the layout, measures the final x, y, width, height (BoundingBox) of every element, and places them absolutely on the slide. This ensures 100% visual accuracy regardless of the layout method used.
3. Fonts: PPTX files use the fonts installed on the viewer's OS. If you use a web font like "Inter", and the user doesn't have it installed, PowerPoint will fallback to Arial.

License

MIT © Atharva Dharmendra Jagtap and dom-to-pptx contributors.

Acknowledgements

This project is built on top of PptxGenJS. Huge thanks to the PptxGenJS maintainers and all contributors — dom-to-pptx leverages and extends their excellent work on PPTX generation.

Bundle & Dependencies

Starting with v1.0.6 dom-to-pptx ships a standalone browser bundle that includes runtime dependencies (for convenience).

• If you use npm / a bundler, run:

npm install dom-to-pptx

• For direct browser usage (single script tag), use the bundled file that already includes pptxgenjs and html2canvas:

<script src="/node_modules/dom-to-pptx/dist/dom-to-pptx.bundle.js"></script>
<script>
  domToPptx.exportToPptx('#slide-container', { fileName: 'report.pptx' });
</script>

If you prefer to manage pptxgenjs yourself (smaller bundle), the legacy dist/dom-to-pptx.min.js remains available and expects pptxgenjs to be loaded separately.

Notes for bundler users (Vite / Rollup / Webpack)

• ESM/CJS builds keep pptxgenjs external.
  • The module outputs (dist/dom-to-pptx.mjs and dist/dom-to-pptx.cjs) do not bundle pptxgenjs so that modern bundlers (like Vite) won't accidentally inline Node-only shims from that dependency. This keeps the ESM artifact safe for browser toolchains but requires you to have pptxgenjs installed in your project when using the module imports:

npm install dom-to-pptx pptxgenjs

• If you get pre-bundling errors in Vite (e.g., esbuild complaining about https, stream, or other Node built-ins), either install pptxgenjs in your app or use the provided standalone UMD bundle.

• Vite quick-workarounds:

  1. Use the bundled UMD in your dev server by adding a resolve alias in vite.config.js:

  import { defineConfig } from 'vite';
  
  export default defineConfig({
    resolve: {
      alias: {
        'dom-to-pptx': '/node_modules/dom-to-pptx/dist/dom-to-pptx.bundle.js',
      },
    },
  });

  2. Or exclude the package from Vite's dependency optimizer (temporary):

  // vite.config.js
  export default {
    optimizeDeps: {
      exclude: ['dom-to-pptx'],
    },
  };

Using the standalone bundle is the simplest path for direct browser usage; using the module build is best for app projects that manage dependencies themselves.

Legacy usage note:

<!-- Load pptxgenjs first -->
<script src="https://cdn.jsdelivr.net/npm/pptxgenjs@latest/dist/pptxgen.bundle.js"></script>
<!-- html2canvas is required by the legacy dom-to-pptx build for backdrop-filter and canvas image processing -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/html2canvas.min.js"></script>
<!-- Then load the legacy dom-to-pptx file that expects the above libs -->
<script src="/node_modules/dom-to-pptx/dist/dom-to-pptx.min.js"></script>
<script>
  document.getElementById('download-btn').addEventListener('click', async () => {
    await domToPptx.exportToPptx('#slide-container', { fileName: 'dashboard-report.pptx' });
  });
</script>