ts-pptx

Appearance

Interface: ImportSlideOptions ​

Options for Presentation.importSlide.

Properties ​

at? ​

optional at?: number

Zero-based insert position in p:sldIdLst (deck order). 0 makes the imported slide first; an at past the current slide count — or omitting it — appends. Use it to place brand bookends (cover at 0, closer appended) around generator-authored interior slides regardless of import order.

carryMasterGraphics? ​

optional carryMasterGraphics?: boolean

preserve/restyle modes only. When true, bake the source slideLayout/slideMaster shape-tree decorations (everything on those shape trees except placeholders — logos, accent curves, footers drawn as shapes) onto the imported slide, behind its own content, so master/layout branding survives the rebind to this deck's master. Their media are copied across.

Under preserve the carried decorations' theme references are flattened like the slide's own content; under restyle they are left symbolic and so re-brand to the destination palette along with the slide — note a carried source logo could recolour unexpectedly under a different palette.

Off by default: it raises fidelity for cover/closer/divider slides at the cost of duplicating shapes that would otherwise live once on the shared master, so opt in only when that branding actually needs to travel with the slide. Ignored unless theme is 'preserve' or 'restyle'.

embedFonts? ​

optional embedFonts?: boolean

Carry the source deck's embedded fonts (p:embeddedFontLst in its presentation.xml) into this deck, so an imported slide that renders with an embedded face keeps it on machines that lack the font. Off by default — fonts live on the presentation, not the slide, so they are only worth copying when you want the embed to travel.

The font binary parts are copied under fresh /ppt/fonts/ names (deduped via the per-source copy registry, so repeated imports copy each face once), the application/x-fontdata Default is added, and entries are merged into this deck's p:embeddedFontLst — de-duplicated by typeface + face slot, so a face this deck already embeds is reused rather than duplicated. The carry is a whole-deck operation (it copies all the source's embedded fonts, not just the faces this one slide uses), since the source list does not record which slide uses which face.

Default ​

ts
false

importNotes? ​

optional importNotes?: boolean

Carry the source slide's speaker notes across. By default (false) the notesSlide relationship is dropped, so the imported slide has no notes.

When set, the source notesSlide is copied and wired to the imported slide. Its slide back-relationship is repointed at the new slide (the source slide is not copied). A presentation has at most one notesMaster: if this deck already has one, the imported notes reuse it (the source notesMaster and its theme are not copied); if it has none, the source notesMaster (and its theme) are copied and registered. The destination's notes styling therefore wins when both decks define one.

Default ​

ts
false

remapLiterals? ​

optional remapLiterals?: boolean

restyle mode only. Push the re-brand past what symbolic references reach, for slides whose palette is partly hardcoded. When true it does two things the plain re-brand cannot:

  • Literal colours — every literal a:srgbClr equal to a source-theme clrScheme slot is rewritten back to a symbolic a:schemeClr (routed through the source clrMap), so it re-resolves against this deck's theme instead of staying its authored RGB. A literal matching no source slot is left untouched.
  • Table styles — any @tableStyleId the slide references is copied from the source tableStyles.xml into this deck's (same id, idempotent, leaving an id the destination already defines alone), so a restyled table keeps its style instead of falling back. The copied definition is itself symbolic, so it re-brands to this deck's theme.

Off by default: it deliberately reinterprets authored literals as theme colours, which is a visual change that needs QA. Ignored unless theme is 'restyle'.

rescale? ​

optional rescale?: boolean | "stretch" | "fit"

What to do when the source slide size differs from this deck's. By default (false) importSlide throws on any mismatch. Set it to rescale the imported geometry onto this deck's canvas instead:

  • 'fit' (or true): uniform scale by min(sx, sy) then center, so aspect ratio is preserved (circles stay circles, rotations hold) and the slack on the longer axis becomes a centered margin. Matches PowerPoint's "Ensure Fit".
  • 'stretch': independent per-axis scale so the content fills the canvas; distorts shapes and cannot faithfully reposition rotated shapes. Matches "Maximize".

Only geometry is rescaled — every top-level shape/group/graphicFrame transform (a:off/a:ext) and table grid (a:gridCol@w, a:tr@h). Font sizes, line widths, and other absolute sizes are left as authored, so heavy down-scaling can leave text overflowing its (now smaller) box. In copy mode the imported layout and master shape trees are rescaled too, so inherited placeholder and background geometry stays aligned; in preserve/restyle the slide rebinds to this deck's master/layout (already the right size), so only the slide is touched.

Default ​

ts
false

theme? ​

optional theme?: "copy" | "preserve" | "restyle"

How the imported slide relates to themes.

  • 'copy' (default): bring the slide's own slideLayout → slideMaster → theme subgraph across, so the slide renders byte-for-byte as authored. A deck stitched from N sources then carries N themes/masters.

  • 'preserve': flatten then attach — bake the source theme's colours and style-matrix fills into the slide XML (so its pixels do not change), then bind it to this deck's existing master/layout instead of importing the source theme. The result is a single-theme file whose imported slides are theme-independent: it fixes renderers that mis-resolve per-slide scheme colours against the wrong (first) theme, and tidies the deck for handoff.

    To stay faithful across the rebind, preserve also bakes the inheritance the rebind would otherwise break explicitly onto the slide: the slide's effective background; each placeholder's inherited geometry (a:xfrm from the matching source layout/master placeholder) so it cannot shift or clip; and each placeholder run's inherited colour and size/weight (sz/b/i) from the source layout/master text styles. Typeface (a:latin) is left to re-bind to the destination theme, like fontRef. By default it does not carry decorative graphics that live on the source master/layout shape tree (logos, accent shapes): those belong to the master preserve deliberately drops. Set carryMasterGraphics to bake them onto the slide instead.

  • 'restyle': re-brand to this deck. Rebind the slide to this deck's master/layout exactly like preserve but skip the flatten — leave every a:schemeClr, style-matrix ref (fillRef/lnRef/effectRef/fontRef), and p:bg bgRef symbolic so they re-resolve against the destination theme. The slide keeps its geometry, text, and structure but adopts this deck's colours/fonts: preserve makes it "look the same everywhere", restyle makes it "look like mine". The slide's own p:clrMapOvr is dropped so the destination master's clrMap governs the re-brand.

    Load-bearing limitation: restyle can only recolour what is symbolic. Anything the source authored as a literal a:srgbClr has no theme reference to re-resolve and stays exactly that colour, so a slide with a baked literal palette re-brands little or nothing. Use restyle for slides built against theme colours/style matrices, not hardcoded RGB — or set remapLiterals to force-remap literals and copy table styles. Re-brand is inherently a visual change (a source accent1 light-on-dark can invert against a dark destination accent1), so its output needs visual QA. A restyled table resolves its @tableStyleId against the destination tableStyles; if the destination lacks that id the table falls back (which remapLiterals also addresses by copying the source style across).