API Reference: Presentation

The main entry point for creating PowerPoint files.

import { Presentation } from 'pptx-craft';

Constructor

new Presentation(options?: PresentationOptions)

PresentationOptions

Option	Type	Description
theme	Partial<Theme>	Custom theme overrides for colors and fonts
slideSize	{ width: Inches; height: Inches; type?: string }	Custom slide dimensions (default: 10 × 7.5 in)
defaultLang	string	Default language for text runs (e.g. 'en-US')
htmlPublishUri	string	URI for HTML publish output
slideUpdateUrl	string	URL for slide update synchronization
coreProperties	object	Dublin Core document metadata (see below)

Core Properties

Property	Type	Description
title	string	Document title
creator	string	Author name
subject	string	Document subject
description	string	Document description
keywords	string	Search keywords
category	string	Document category

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.

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

Masters & Layouts

defineSlideMaster(def: SlideMasterDef): this

Define or replace the default slide master.

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

SlideMasterDef

Field	Type	Description
name	string	Master name
background	string	Background color (hex)
elements	IElement[]	Optional fixed elements on every slide

defineLayout(def: SlideLayoutDef): this

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

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

Field	Type	Description
name	string	Layout name (used in addSlide())
type	LayoutType	Layout category
placeholders	PlaceholderDef[]	Placeholder positions

Built-in Layouts

The library provides five built-in layouts via builtinLayouts:

Name	Type	Description
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.

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

defineHandoutMaster(def?: HandoutMasterDef): this

Define the handout master for printed handouts.

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

Presentation Properties

setShowProperties(props: SlideShowProperties): this

Configure slideshow playback behavior.

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

SlideShowProperties

Option	Type	Description
loop	boolean	Loop the slideshow continuously
showNarration	boolean	Play embedded narration audio
showAnimation	boolean	Play slide animations
useTimings	boolean	Use recorded timings for auto-advance

setPrintProperties(props: PrintProperties): this

Configure print-related properties.

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

PrintProperties

Option	Type	Description
frameSlides	boolean	Print a border frame around each slide
hiddenSlides	boolean	Include hidden slides when printing

setViewProperties(props: ViewProperties): this

Set the default editing view that opens in PowerPoint.

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

ViewProperties

Option	Type	Description
lastView	LastViewType	The 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.

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.

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.

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.

const buffer = pptx.toBuffer();

toFile(path: string): Promise<void>

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

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