Skip to content

API Reference: Presentation ​

The main entry point for creating PowerPoint files.

typescript
import { Presentation } from 'pptx-craft';

Constructor ​

typescript
new Presentation(options?: PresentationOptions)

PresentationOptions ​

OptionTypeDescription
themePartial<Theme>Custom theme overrides for colors and fonts
slideSize{ width: Inches; height: Inches; type?: string }Custom slide dimensions (default: 10 × 7.5 in)
defaultLangstringDefault language for text runs (e.g. 'en-US')
htmlPublishUristringURI for HTML publish output
slideUpdateUrlstringURL for slide update synchronization
corePropertiesobjectDublin Core document metadata (see below)

Core Properties ​

PropertyTypeDescription
titlestringDocument title
creatorstringAuthor name
subjectstringDocument subject
descriptionstringDocument description
keywordsstringSearch keywords
categorystringDocument category
typescript
const pptx = new Presentation({
  theme: {
    name: 'Corporate',
    colors: { accent1: '0066CC', accent2: 'FF6600' },
    fonts: { majorFont: 'Georgia', minorFont: 'Verdana' },
  },
  slideSize: { width: 13.333, height: 7.5 },
  defaultLang: 'en-US',
  coreProperties: {
    title: 'Q4 Report',
    creator: 'Jane Doe',
  },
});

Slides ​

addSlide(layoutName?: string): SlideBuilder ​

Add a new slide, optionally using a named layout. Returns a SlideBuilder for populating the slide.

typescript
const slide = pptx.addSlide();
const slide2 = pptx.addSlide('Title and Content');

Masters & Layouts ​

defineSlideMaster(def: SlideMasterDef): this ​

Define or replace the default slide master.

typescript
pptx.defineSlideMaster({
  name: 'Corporate',
  background: '003366',
  elements: [/* optional fixed elements */],
});

SlideMasterDef ​

FieldTypeDescription
namestringMaster name
backgroundstringBackground color (hex)
elementsIElement[]Optional fixed elements on every slide

defineLayout(def: SlideLayoutDef): this ​

Register a named slide layout with placeholders. Reference the name in addSlide().

typescript
pptx.defineLayout({
  name: 'My Layout',
  type: 'titleAndContent',
  placeholders: [
    { type: 'title', placement: { x: 0.5, y: 0.5, w: 9, h: 1 }, idx: 0 },
    { type: 'body', placement: { x: 0.5, y: 2, w: 9, h: 5 }, idx: 1 },
  ],
});

SlideLayoutDef ​

FieldTypeDescription
namestringLayout name (used in addSlide())
typeLayoutTypeLayout category
placeholdersPlaceholderDef[]Placeholder positions

Built-in Layouts ​

The library provides five built-in layouts via builtinLayouts:

NameTypeDescription
blank'blank'Empty layout (default)
title'title'Centered title and subtitle
titleAndContent'titleAndContent'Title at top, content area below
sectionHeader'sectionHeader'Section divider layout
twoContent'twoContent'Two-column content layout

defineNotesMaster(def?: NotesMasterDef): this ​

Define the notes master for speaker notes formatting.

typescript
pptx.defineNotesMaster({ name: 'Custom Notes' });

defineHandoutMaster(def?: HandoutMasterDef): this ​

Define the handout master for printed handouts.

typescript
pptx.defineHandoutMaster({ name: 'Custom Handout' });

Presentation Properties ​

setShowProperties(props: SlideShowProperties): this ​

Configure slideshow playback behavior.

typescript
pptx.setShowProperties({
  loop: true,
  showNarration: true,
  showAnimation: true,
  useTimings: true,
});

SlideShowProperties ​

OptionTypeDescription
loopbooleanLoop the slideshow continuously
showNarrationbooleanPlay embedded narration audio
showAnimationbooleanPlay slide animations
useTimingsbooleanUse recorded timings for auto-advance

setPrintProperties(props: PrintProperties): this ​

Configure print-related properties.

typescript
pptx.setPrintProperties({
  frameSlides: true,
  hiddenSlides: false,
});

PrintProperties ​

OptionTypeDescription
frameSlidesbooleanPrint a border frame around each slide
hiddenSlidesbooleanInclude hidden slides when printing

setViewProperties(props: ViewProperties): this ​

Set the default editing view that opens in PowerPoint.

typescript
pptx.setViewProperties({ lastView: 'sldSorterView' });

ViewProperties ​

OptionTypeDescription
lastViewLastViewTypeThe view active when last saved

LastViewType values: 'sldView' | 'sldMasterView' | 'notesView' | 'handoutView' | 'sldSorterView'

Comments ​

defineCommentAuthor(name: string, initials: string): number ​

Register a comment author. Returns the author ID. If the name already exists, the existing ID is reused.

typescript
const authorId = pptx.defineCommentAuthor('Alice', 'A');
const slide = pptx.addSlide();
slide.addComment('Great slide!', authorId, { position: { x: 100, y: 100 } });

Tags ​

setTags(tags: Record<string, string>): this ​

Set user-defined key-value tags on the presentation.

typescript
pptx.setTags({ version: '2.0', department: 'Engineering' });

Plugins ​

use(plugin: IPlugin): this ​

Register a plugin to extend the element registry with custom element types and serializers.

typescript
pptx.use(myPlugin);

See the Plugins guide for details on creating plugins.

Output ​

toBuffer(): Uint8Array ​

Generate the .pptx file as a buffer. Works in all JavaScript environments.

typescript
const buffer = pptx.toBuffer();

toFile(path: string): Promise<void> ​

Write the .pptx file to disk. Node.js only.

typescript
await pptx.toFile('output.pptx');

Released under the MIT License.