API Reference

buildPptx

The main function that takes an XML string and generates a PowerPoint presentation.

Signature


async function buildPptx(
  xml: string,
  slideSize: { w: number; h: number },
  options?: {
    master?: SlideMasterOptions;
    masterPptx?: ArrayBuffer | Uint8Array;
    textMeasurement?: TextMeasurementMode;
    fonts?: FontInput[];
    autoFit?: boolean;
    strict?: boolean;
  },
): Promise<BuildPptxResult>;

Parameters

`xml` (required)

An XML string describing the slide content. Each top-level <Slide> element represents one slide and wraps that slide’s content. See Nodes for available node types and llm.txt for the complete XML reference.


const xml = `
<Slide>
  <VStack w="100%" h="max" padding="48">
    <Text fontSize="32" bold="true">Slide 1</Text>
  </VStack>
</Slide>
<Slide>
  <VStack w="100%" h="max" padding="48">
    <Text fontSize="24">Slide 2</Text>
  </VStack>
</Slide>
`;

`slideSize` (required)

The slide dimensions in pixels. Internally converted to inches at 96 DPI.


// 16:9 (recommended)
{ w: 1280, h: 720 }
 
// 4:3
{ w: 960, h: 720 }

`options` (optional)

Property	Type	Default	Description
`master`	`SlideMasterOptions`	`undefined`	Slide master settings
`masterPptx`	`ArrayBuffer \| Uint8Array`	`undefined`	Existing PPTX file to use as master (extracts background). See Master Slide.
`textMeasurement`	`TextMeasurementMode`	`"auto"`	Text width measurement method
`fonts`	`FontInput[]`	`[]`	Custom font bytes used for text width measurement. See Text Measurement.
`autoFit`	`boolean`	`true`	Auto-fit content when it overflows slides
`strict`	`boolean`	`false`	Throw `DiagnosticsError` if any diagnostics are collected

Return Value

Returns a BuildPptxResult object:

Field	Type	Description
`pptx`	`WritablePptx`	The generated presentation output facade
`diagnostics`	`Diagnostic[]`	Warnings collected during the build process


const { pptx, diagnostics } = await buildPptx(xml, { w: 1280, h: 720 });
 
// Save to file (Node.js)
await pptx.writeFile({ fileName: "output.pptx" });
 
// Check for warnings
if (diagnostics.length > 0) {
  console.warn("Build warnings:", diagnostics);
}

WritablePptx は PPTX 出力専用の facade です。以前の戻り値に含まれていた pptxgenjs の編集 API は提供しません。スライド内容は XML、マスター内容は SlideMasterOptions で指定してください。

Diagnostic Codes

Each Diagnostic has a code and a human-readable message. Diagnostics are warnings — the build itself completes unless strict: true is set.

Code	Meaning
`IMAGE_MEASURE_FAILED`	Failed to measure an image’s size. A default size is used.
`IMAGE_NOT_PREFETCHED`	The size of a URL image was not prefetched. A default size is used.
`AUTOFIT_OVERFLOW`	Content still exceeds the slide height after all autoFit adjustments. When available, the message identifies the furthest leaf node and reports its `y`, height, and bottom edge.
`SCALE_BELOW_THRESHOLD`	A node’s shrink scale factor fell below the minimum threshold. Content may overflow.
`MASTER_PPTX_PARSE_FAILED`	Failed to parse the file passed as `masterPptx`.
`ARROW_REF_NOT_FOUND`	An `Arrow`’s `from` / `to` id was not found on the slide.
`ARROW_REF_NOT_CONNECTABLE`	An `Arrow` reference exists, but does not point to a `Text` node or a connector-compatible `Shape` geometry (`rect`, `roundRect`, or `ellipse`).
`DUPLICATE_NODE_ID`	The same `id` is used by multiple nodes. Only the first occurrence is used for Arrow references.
`NODE_OUT_OF_BOUNDS`	A node’s rectangle extends beyond the slide bounds. The message identifies the slide, the node (tag / `id` / path from the root), and the overflowing edges. Reported for the node closest to the cause (the deepest offending node). Nodes with `rotate` and `Line` / `Arrow` nodes are excluded to avoid false positives.
`NODE_OVERLAP`	Siblings inside `VStack` / `HStack` overlap unintentionally. Intentional overlaps are excluded: children of `Layer`, `position="absolute"` nodes, negative `margin` / `gap`, and nodes with an explicit `zIndex`.

Errors

ParseXmlError — Thrown when the XML string is invalid or contains unknown tags/attributes.
DiagnosticsError — Thrown when strict: true is set and diagnostics are collected during build.


import { buildPptx, ParseXmlError, DiagnosticsError } from "@hirokisakabe/pom";
 
try {
  const { pptx } = await buildPptx(xml, { w: 1280, h: 720 }, { strict: true });
} catch (e) {
  if (e instanceof ParseXmlError) {
    console.error("Invalid XML:", e.message);
  }
  if (e instanceof DiagnosticsError) {
    console.error("Build diagnostics:", e.diagnostics);
  }
}

Options

master

Defines a slide master with static objects and page numbers applied to all slides. See Master Slide for full documentation.


const { pptx } = await buildPptx(
  xml,
  { w: 1280, h: 720 },
  {
    master: {
      title: "MY_MASTER",
      background: { color: "F8FAFC" },
      objects: [
        {
          type: "text",
          text: "Header",
          x: 48,
          y: 12,
          w: 200,
          h: 28,
          fontSize: 14,
        },
      ],
      slideNumber: { x: 1100, y: 690, fontSize: 10 },
    },
  },
);

textMeasurement

Controls how text width is measured for line breaking and layout. Accepts "opentype", "fallback", or "auto" (default). See Text Measurement for details on each mode.

fonts

Registers custom font data for layout measurement. Both ArrayBuffer and Uint8Array are accepted, so the same API works in Node.js and browsers.


interface FontInput {
  name?: string;
  data: ArrayBuffer | Uint8Array;
  weight?: "normal" | "bold" | number;
}


import type { FontInput } from "@hirokisakabe/pom";
 
const fonts: FontInput[] = [
  { name: "My Font", data: regularFontBytes },
  { name: "My Font", data: boldFontBytes, weight: "bold" },
];
 
const { pptx } = await buildPptx(xml, { w: 1280, h: 720 }, { fonts });

name is an optional family alias. The family names stored inside the font are always registered as well. When weight is omitted, pom uses font metadata when available and otherwise treats the face as regular. Family matching is case-insensitive, and bold text falls back to the registered regular face when no bold face is available.

Custom font data is used only for advance-width measurement during layout. pom does not embed the font in the generated PPTX or install it in PowerPoint or the operating system; install or distribute the font separately where the presentation is viewed.

autoFit

When enabled (default), content that exceeds the slide height is automatically adjusted to fit. Adjustments are applied in priority order:

Reduce table row heights
Reduce text font sizes
Reduce gap / padding
Uniform scaling (fallback)


// Disable auto-fit
const { pptx } = await buildPptx(
  xml,
  { w: 1280, h: 720 },
  {
    autoFit: false,
  },
);

Exported Types


import type {
  BuildPptxResult,
  FontInput,
  TextMeasurementMode,
  Diagnostic,
  DiagnosticCode,
  SlideMasterOptions,
  SlideMasterBackground,
  SlideMasterMargin,
  MasterObject,
  MasterTextObject,
  MasterImageObject,
  MasterRectObject,
  MasterLineObject,
  SlideNumberOptions,
} from "@hirokisakabe/pom";