API Reference: SlideBuilder

Returned by Presentation.addSlide(). All methods return this for chaining.

const slide = pptx.addSlide();
slide
  .addText('Hello', { x: 1, y: 1, w: 8, h: 1, fontSize: 24 })
  .addShape('rect', { x: 1, y: 3, w: 3, h: 2, fill: '0066CC' });

Elements

addText(text: string, opts?: TextOptions): this

Add a text box to the slide. The text string is split on newlines into paragraphs. Options combine placement, run-level, paragraph-level, and text body formatting.

slide.addText('Hello World', {
  x: 1, y: 1, w: 8, h: 1.5,
  fontSize: 24,
  bold: true,
  color: '003366',
  align: 'center',
  verticalAlign: 'middle',
  fill: 'F0F0F0',
  line: { color: 'CCCCCC', width: 1 },
});

See TextOptions for the full options reference.

addImage(opts: ImageOptions): this

Add an image from a file path or binary data.

slide.addImage({ path: './logo.png', x: 1, y: 1, w: 3, h: 2 });

slide.addImage({
  data: pngBuffer,
  contentType: 'image/png',
  x: 5, y: 1, w: 4, h: 3,
  border: { color: '000000', width: 2 },
  effects: { shadow: { type: 'outer', blur: 4, offset: 3, angle: 45 } },
  hyperlink: { url: 'https://example.com' },
});

See ImageOptions for the full options reference.

addShape(geometry: PresetGeometry, opts?: ShapeOptions): this

Add a preset geometry shape. The first argument is the shape type; see PresetGeometry for all available shapes.

slide.addShape('roundRect', {
  x: 1, y: 1, w: 4, h: 2,
  fill: '0066CC',
  line: { color: '003366', width: 2 },
  text: 'Click me',
  textRunOptions: { color: 'FFFFFF', bold: true },
  textOptions: { verticalAlign: 'middle' },
  hyperlink: { url: 'https://example.com' },
});

See ShapeOptions for the full options reference.

addTable(rows: TableRow[], opts?: TableOptions): this

Add a table with rows and columns.

slide.addTable(
  [
    [
      { text: 'Name', options: { bold: true, fill: '003366', color: 'FFFFFF' } },
      { text: 'Score', options: { bold: true, fill: '003366', color: 'FFFFFF' } },
    ],
    [{ text: 'Alice' }, { text: '95' }],
    [{ text: 'Bob' }, { text: '87' }],
  ],
  {
    x: 1, y: 1, w: 8, h: 3,
    colWidths: [5, 3],
    border: { color: 'CCCCCC', width: 1 },
    firstRow: true,
  },
);

See TableRow, TableCell, and TableOptions for the full options reference.

addChart(type: ChartType, data: ChartData, opts?: ChartOptions): this

Add a native PowerPoint chart. Defaults to 6×4 inches if width/height are not specified.

slide.addChart('col', {
  categories: ['Q1', 'Q2', 'Q3', 'Q4'],
  series: [
    { name: 'Revenue', values: [100, 150, 120, 180], color: '0066CC' },
    { name: 'Expenses', values: [80, 90, 85, 110], color: 'FF6600' },
  ],
}, {
  x: 1, y: 1,
  title: 'Quarterly Results',
  showLegend: true,
  showGridLines: true,
  catAxis: { title: 'Quarter' },
  valAxis: { title: 'Amount ($K)', format: '#,##0' },
});

See ChartType, ChartData, and ChartOptions for the full options reference.

addVideo(opts: MediaOptions): this

Embed a video. Defaults to 6×4 inches.

slide.addVideo({
  path: './intro.mp4',
  x: 2, y: 1.5, w: 6, h: 4,
  poster: { path: './thumbnail.png' },
  playback: { autoPlay: true, showControls: true },
});

addAudio(opts: MediaOptions): this

Embed audio. Defaults to 1×1 inch.

slide.addAudio({
  path: './narration.mp3',
  x: 0.5, y: 0.5,
  playback: { autoPlay: true, loop: true },
});

See MediaOptions for the full options reference.

addElement(element: IElement): this

Add a pre-built element directly. Useful for plugin-provided element types.

slide.addElement(myCustomElement);

addGroup(buildFn: (group: GroupBuilder) => void, opts?: GroupOptions): this

Add a group of elements that are positioned and transformed together.

slide.addGroup(
  (group) => {
    group.addShape('rect', { x: 0, y: 0, w: 2, h: 1, fill: 'FF0000' });
    group.addText('Label', { x: 0.2, y: 0.2, w: 1.6, h: 0.6, color: 'FFFFFF' });
  },
  { x: 3, y: 2, w: 4, h: 3 },
);

GroupBuilder Methods

Method	Description
addShape(geometry, opts?)	Add a shape to the group
addText(text, opts?)	Add a text box to the group
addImage(opts)	Add an image to the group
addElement(element)	Add a pre-built element to the group

addConnector(opts: ConnectorOptions): this

Add a connector line between points on the slide.

slide.addConnector({
  x: 1, y: 1, w: 4, h: 2,
  type: 'elbow',
  line: { color: '333333', width: 2, dash: 'dash' },
  startArrow: { type: 'none' },
  endArrow: { type: 'triangle', width: 'med', length: 'med' },
});

See ConnectorOptions for the full options reference.

Slide Metadata

setNotes(notes: string): this

Set speaker notes for this slide.

slide.setNotes('Remember to mention the quarterly results.');

setBackground(bg: SlideBackground): this

Set the background fill or image for this slide.

// Solid color
slide.setBackground({ color: '003366' });

// Gradient fill
slide.setBackground({
  fill: {
    type: 'linear',
    angle: 90,
    stops: [
      { position: 0, color: '003366' },
      { position: 100, color: '0099FF' },
    ],
  },
});

See SlideBackground for fill options.

setTransition(transition: SlideTransition): this

Set the transition effect for advancing to this slide.

slide.setTransition({
  type: 'fade',
  duration: 500,
  advanceAfter: 3000,
  advanceOnClick: true,
});

See SlideTransition for the full options reference.

addAnimation(anim: Animation): this

Add an animation to the slide's animation sequence. The elementIndex is the zero-based index of the target element in the order it was added.

slide.addText('Animated', { x: 2, y: 2, w: 6, h: 2, fontSize: 36 }); // index 0
slide.addAnimation({
  elementIndex: 0,
  effect: 'fade',
  category: 'entrance',
  trigger: 'onClick',
  duration: 1000,
});

See Animation for the full options reference.

addComment(text: string, authorId: number, opts?): this

Add a comment to this slide. The authorId must be registered via Presentation.defineCommentAuthor().

const authorId = pptx.defineCommentAuthor('Alice', 'A');
const slide = pptx.addSlide();
slide.addComment('Needs review', authorId, {
  position: { x: 100, y: 200 },
  date: '2024-01-15T10:30:00Z',
});

Option	Type	Description
position	{ x: number; y: number }	Comment anchor position in points
date	string	ISO 8601 timestamp

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

Set user-defined key-value tags on this slide.

slide.setTags({ section: 'intro', status: 'draft' });

setSyncData(data: SlideSyncData): this

Set synchronization metadata for collaborative editing.

slide.setSyncData({
  serverSldId: 'abc123',
  serverSldModifiedTime: '2024-01-15T10:30:00Z',
  clientInsertedTime: '2024-01-15T10:00:00Z',
});