Insert and format images

Use image commands on an open presentation. Each command returns a result that you must check.

Insert image bytes

Pass the encoded file bytes, MIME type, and stored pixel dimensions. This function inserts a PNG:

import type { Editor } from '@pptx-editor.dev/core/contracts';

export function insertPng(editor: Editor, bytes: Uint8Array, width: number, height: number) {
  const result = editor.exec({
    type: 'insertImage',
    bytes,
    mime: 'image/png',
    width,
    height,
  });
  if (!result.ok) throw new Error(result.reason);
}

The editor centers the picture and reduces it when needed to fit the slide. The inserted picture becomes selected.

Fill an empty placeholder

When the current slide has an empty content or picture placeholder, insertImage puts the picture there instead. It fills the placeholder that is selected or holds the caret, or else the first one on the slide. The picture keeps the placeholder's name and index. Animations and connectors that name the placeholder go on to name the picture.

• A content placeholder holds the whole picture, centered, and never larger than the picture's own size.
• A picture placeholder is filled to its edges. The picture is cropped from the middle to the placeholder's proportions, and it keeps the placeholder's geometry, so a round frame stays round.
• A placeholder with text, or with its own fill, line, or effect, is passed over. The picture fills the next empty placeholder, or goes to the middle of the slide when none is left.

In the editor, each empty placeholder shows a dotted outline. Empty content and table placeholders also show a Table button in their middle, and empty content and picture placeholders show a Picture button. Table inserts a 3 × 3 table, and Picture opens the file chooser. Keyboard users insert from the Insert menu, which fills the placeholder in the same way. The outline and buttons are editing chrome: thumbnails, the slide show, PDF export, and saved files never show them. One undo brings the empty placeholder back.

The insert buttons hide while another object is selected or edited. Clear the selection or click the empty placeholder's border to show its buttons. Clicking inside a placeholder that accepts text starts text editing instead.

The command inserts on the current slide at execution time. If you load image bytes asynchronously, confirm the target before you execute.

Resize the selected picture

Picture geometry uses English Metric Units (EMU). One inch equals 914,400 EMU; one point equals 12,700 EMU.

Set both dimensions to preserve the desired aspect ratio:

import type { Editor } from '@pptx-editor.dev/core/contracts';

export function resizePicture(editor: Editor) {
  const result = editor.exec({
    type: 'setImageProperties',
    widthEmu: 3 * 914400,
    heightEmu: 2 * 914400,
  });
  if (!result.ok) throw new Error(result.reason);
}

setImageProperties also accepts rotationDegrees and crop. Omitted fields retain their values.

Set alt text

Describe a picture after selecting it. Set decorative: true only when the picture adds no information:

import type { Editor } from '@pptx-editor.dev/core/contracts';

export function describePicture(editor: Editor, description: string) {
  const result = editor.exec({
    type: 'setAltText',
    description,
    decorative: false,
  });
  if (!result.ok) throw new Error(result.reason);
}

Replace or reset a picture

replaceImage replaces the selected picture with encoded image bytes. It accepts bytes, mime, and optional pixel width and height.

Replacement fits the image into the existing frame and resets its crop. Border, effects, and adjustments remain.

resetImage removes picture adjustments, border, effects, and crop-to-shape formatting. Add size: true to restore its natural size and remove the crop.

A selection can change while a file loads. Recheck the selected picture before replacement, or use the built-in picture dialog.

Slides with many large pictures

The editor limits the decoded pixels that the pictures of one slide, layout, or master hold on screen. The limit is about 105 million pixels for the PNG, JPEG, GIF, BMP, and WebP pictures of each part. SVG pictures do not count.

When a part's pictures exceed the limit, the editor applies these rules:

• Each picture draws scaled down to its share of the limit, in the editor and in the slide show. The browser decodes and scales it off the main thread.
• The picture placeholder shows until a scaled picture is ready.
• After an edit, scaled sizes stay until a picture's share moves by more than 25%. A part can then hold up to about 1.56 times the limit. A picture keeps its last scaled size until its new size is ready.
• An animated GIF shows its first frame.
• PDF and image export, copy, and save use the stored pictures at their full size.

A slide within the limit draws its pictures at their stored size.

See also

• Dialogs
• Accessibility
• Export presentations