Link to a slide, a custom show, a file, or an email address

Link selected text to a slide, a relative slide, a custom show, another file, or an email address.

Use the setLink command to link the selected text to a slide, a custom show, another file, or an email address. The command takes one url string for every kind of link, and each link is one undo step.

Link to a slide

This helper accepts an open PptxEditorInstance with text selected, and links that text to slide 3:

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

export function linkToSlide(editor: PptxEditorInstance, slideNumber: number) {
  const result = editor.exec({ type: 'setLink', url: `#slide-${slideNumber}` });
  if (!result.ok) throw new Error(result.reason);
}

// linkToSlide(editor, 3);

Slide numbers start at 1. The link follows its slide when slides move. When you delete the slide, the editor removes the link.

To jump relative to the slide that shows, use one of these forms:

URL	Goes to
`#first-slide`	The first slide
`#last-slide`	The last slide
`#next-slide`	The slide after the one that shows
`#previous-slide`	The slide before the one that shows

Link to a custom show

A custom show is a named list of the deck's slides. editor.snapshot().customShows lists the shows of the open deck, each with its id and name. Link to a show with #custom-show-<id>. Add ?return=true to come back to the linking slide after the show's last slide:

const show = editor.snapshot().customShows?.find((s) => s.name === 'Short');
if (show) editor.exec({ type: 'setLink', url: `#custom-show-${show.id}?return=true` });

The file stores the link with no relationship and the action ppaction://customshow?id=<id>&return=true. setLink refuses an id that the deck does not have with errors.customShowNotFound.

Link to another file

Link to a file next to the presentation with a relative path that starts with ./ or ../:

editor.exec({ type: 'setLink', url: './docs/Q3 report.pdf' });

The file stores the path, percent-encoded, as an external hyperlink target: docs/Q3%20report.pdf. A presentation application opens the file relative to the deck. The editor never opens or fetches it: a browser cannot reach a file next to the deck.

Only a URL that starts with ./ or ../ is a file link. setLink reads a bare name such as report.pdf as a web address (https://report.pdf). In the default editor, Other file adds ./ to a path that has no prefix.

setLink checks a file path strictly and refuses it with errors.unsafeFileLink in these cases:

It has more than two leading ../ steps, or a . or .. step after the first name.
It names a scheme, a drive, or an absolute path, or holds a backslash, a colon, or a control character.
A name in it ends with a dot or a space, or is a device name such as CON or nul.txt.
The file is not a document, picture, sound, or video file. The file name must end with an extension such as .pdf, .docx, .xlsx, .pptx, .txt, .csv, .png, .jpg, .mp3, or .mp4. A program, a script, a web page, a document with macros, or a disk image is refused.

Link to an email address

Use a mailto: URL. Percent-encode the subject, so that its text cannot add other fields:

const subject = encodeURIComponent('Q3 plans');
editor.exec({ type: 'setLink', url: `mailto:ana@example.com?subject=${subject}` });

Read a link

With a caret inside linked text, editor.snapshot().format?.link returns the same URL forms: #slide-3, #next-slide, #custom-show-2?return=true, ./docs/Q3 report.pdf, or the mailto: address.

What users see

In the default editor, the link popup has a Link to choice: Web address, Email, Slide, Custom show, or Other file. Custom show shows only when the deck has a custom show, or when the link already goes to one. It lists the deck's shows by name, with Return to this slide after the show. Other file takes a relative path.

A click into a slide link shows the slide it goes to as a button, such as Slide 3. The button's accessible name is "Go to Slide 3", and it shows that slide in the editor. A custom show link shows its show, such as "Custom show: Short". A file link shows its path. Copy is hidden for these links. In the slide show, a click on a slide link moves the show to that slide. A click on a web or email link opens it in a new tab. Custom show and file links do nothing in the slide show.

Limits

setLink refuses a slide number past the end, #slide-0, and any other # form with errors.slideNotFound.
The slide show does not run custom shows.
Copy and paste keeps a link to another file only when its path passes the checks of setLink.
Links to programs (ppaction://program) keep their action and target on save, and the editor never runs them. setLink never writes such a link: this is a deliberate security limit. Edit replaces the link.
mailto: fields other than the subject, such as cc and body, stay in the link when you edit the address or the subject.