Overview

Every PowerPoint layout is built on placeholders — predefined zones where content goes. The pptx.dev API maps your JSON content to these placeholders automatically, so you get properly positioned text, images, and charts without manual layout work.

Placeholder Types

How the API Maps Content to Placeholders

When you send a slide definition, the API:

1. Reads the layout to determine which placeholders exist
2. Maps your content fields to the corresponding placeholders
3. Applies the color scheme and font scheme to style each placeholder
4. Renders the final slide

{
  "layout": "text-2x-left",
  "content": {
    "heading": "Key Highlights",
    "items": [
      {
        "heading": "Revenue Growth",
        "body": "Revenue increased 24% year-over-year."
      },
      {
        "heading": "Market Expansion",
        "body": "Entered three new European markets in Q1."
      }
    ]
  }
}

In this example:

• heading maps to the title placeholder
• items[0].heading maps to the first column heading
• items[0].body maps to the first column body text
• Same pattern for the second item

Multi-Item Layouts

Layouts with 2x, 3x, 4x, 5x, or 6x in their name expect an items array. Each item fills one set of placeholders:

{
  "layout": "number-3x-title-center",
  "content": {
    "heading": "Q1 Metrics",
    "items": [
      { "value": "$1.2M", "label": "Revenue" },
      { "value": "94%", "label": "Retention" },
      { "value": "72", "label": "NPS" }
    ]
  }
}

The API distributes items across the layout's placeholder positions automatically.

Image Placeholders

Image placeholders accept URLs. The API fetches the image at generation time and embeds it:

{
  "layout": "image-1x-crop-title-center",
  "content": {
    "heading": "Our New Office",
    "image": "https://example.com/office-photo.jpg"
  }
}

Slide Image vs. Content Image

• Slide image (slideImage) — full-bleed background behind all content
• Content image (image) — placed in a specific image placeholder on the slide

Use slide images for atmosphere. Use content images for specific visuals.

Tips

1. Match your content to the layout. A number-3x layout expects 3 items — sending 2 or 4 may not render as expected.
2. Check the gallery for each layout's placeholder map before writing your content.
3. Keep text short. Placeholders have fixed sizes — long text will be truncated or shrunk.

Next Steps

• Browse all layouts to see placeholder configurations
• Learn about title slides and their placeholders
• Explore image slides for visual content