@pptx-editor.dev/core

Core provides the PPTX engine and browser editor. React and Vue add interface components around the same editor contract.

Install

Install the package directly when your application imports its APIs:

npm install @pptx-editor.dev/core

Keep one resolved copy of core in your application. The adapters use it as a peer dependency.

Create an editor

This browser helper mounts an editor into an existing element. It returns the instance for your controls and cleanup:

import { createPptxEditor } from '@pptx-editor.dev/core/editor';
import '@pptx-editor.dev/core/styles/editor.css';

export async function mountPresentation(container: HTMLElement, bytes: Uint8Array) {
  const editor = createPptxEditor({ zoom: 'fit' });
  container.classList.add('pptx-editor');
  try {
    editor.attach(container);
    const result = await editor.load(bytes);
    if (!result.ok) throw new Error(result.reason);
    return editor;
  } catch (error) {
    editor.destroy();
    throw error;
  }
}

Give the container a height and available width. Call editor.destroy() when your application removes this editor permanently.

The core editor does not add a toolbar, slide rail, or menus. Use the adapters for those components.

Choose an import

Use the editor entry point for browser integration. Other entry points expose the engine layers:

For server-side document editing, start with the Editing API.

Read state and run commands

Use snapshot() for state and exec() for edits. This helper adds a slide when the command is available:

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

export function addSlide(editor: Editor) {
  const command = { type: 'addSlide' } as const;
  const allowed = editor.can(command);
  if (!allowed.ok) return allowed;
  return editor.exec(command);
}

Check the final result even after can(). Commands can be refused when their target is unavailable. For a large target, can() makes a shorter check. On a selection of more than 250 shapes, the commands that arrange shapes (order, alignObjects, distributeObjects, flipObjects, duplicate, delete, group, and ungroup) get a check of the editing mode only, and their argument is not checked. Other commands are checked on the first 250 shapes, and a refusal there gets the full check. A command that passes on the first 250 shapes can still be refused by exec(). The duplicate command also counts a selection of more than 20,000 XML nodes as large, and the applyLayout and resetSlides commands a named slide of more than 20,000 XML nodes. The addSlide and addSection commands always get the full check. While you type, the formatting answers of the text box hold until 300 ms after the last key. exec() makes the full check and returns the refusal reason.

Choose an event

Use onEditorEvent(editor, name, handler) to observe a specific change. It returns an unsubscribe function.

Use subscribe() when you also need zoom or other view changes. Dispose every subscription when its consumer unmounts.

See also

• Editor mount modes
• Engine architecture
• Load and save presentations