Plugins

Extend pptx-craft with custom element types.

Plugin Interface

import type { IPlugin, IRegistry, IElement, IElementSerializer } from 'pptx-craft';

const myPlugin: IPlugin = {
  name: 'my-plugin',
  install(registry: IRegistry) {
    registry.registerElement('custom', mySerializer);
  },
};

Creating a Custom Element

Implement the IElement interface. Every element needs a type discriminator and a placement:

import type { IElement, Placement } from 'pptx-craft';

class BadgeElement implements IElement {
  readonly type = 'badge';
  placement: Placement;
  name?: string;

  constructor(
    public label: string,
    placement: Placement,
  ) {
    this.placement = placement;
  }
}

Creating a Serializer

The serializer converts your element into an OOXML XML string that the writer embeds in the slide:

import type { IElementSerializer, SerializationContext } from 'pptx-craft';

const badgeSerializer: IElementSerializer<BadgeElement> = {
  type: 'badge',
  serialize(element: BadgeElement, ctx: SerializationContext): string {
    return `<p:sp><!-- your XML here --></p:sp>`;
  },
};

If your element includes binary resources (images, media), use ctx.addRelationship() to register them and get a relationship ID you can reference in the XML:

const imageSerializer: IElementSerializer<CustomImageElement> = {
  type: 'custom-image',
  serialize(element, ctx) {
    const rId = ctx.addRelationship(
      'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image',
      'media/custom.png',
      element.imageData,
    );
    return `<p:pic><!-- reference ${rId} in your XML --></p:pic>`;
  },
};

Registering a Plugin

const pptx = new Presentation();
pptx.use(myPlugin);

The plugin's install method receives the registry, where you register your serializer. When the writer encounters your element type, it delegates to your serializer.

Serialization Context

Your serializer receives a SerializationContext with:

Property	Type	Description
addRelationship(type, target, data?)	(string, string, Uint8Array?) => string	Register a binary resource and get back an rId
theme	Theme	Current presentation theme (colors, fonts)
slideIndex	number	Current slide index (0-based)