Dialog reference

This page lists the popup keys, the dialog fields, and the popup rules. For the tasks, see Dialogs.

Popup registry keys

Pass the map through popups on PptxEditor.Root. A function renders that surface. false turns off its automatic rendering.

What a false entry does

A false entry turns off automatic rendering for that key. It does not turn off the operation. setLink, editor.find, setSlideBackground, setFontFormat, setParagraphFormat, setBulletFormat, setColumns, setAltText, setImageProperties, insertEquation, and setEquation keep working from the API. useEditorCommand('image.altText').execute(description) also sets the description with the popup off.

The toolbar control or menu row that opens the surface stays visible. It is disabled with a reason, such as "Links are turned off in this editor". There are two exceptions:

• The link control opens your panel while a useHyperlinkPopup() panel of yours is mounted. See Build your own link panel.
• A row inside a toolbar dropdown that opens a dialog is left out of the dropdown. Examples are Line Spacing Options…, More Spacing…, Bullets and numbering… in a gallery, and More columns…. A disabled row there has no use, and the other rows still work.

When you replace an input popup, give your users another way to reach its operation.

Open a dialog by key

useEditorDialog(key).open() opens a modal dialog from your own control. The keys are pageSetup, background, font, paragraph, bulletsAndNumbering, columns, imageAltText, imageProperties, and equation. isAvailable is false when the entry is false.

The link popup renderer

PptxEditor.Root hosts the link popup, so it opens with no toolbar on the page. It has two modes:

• Reading. A click into linked text opens a small panel under the caret: the target, Copy, Edit, and Remove link. The caret keeps the keyboard, so typing goes on. Press F6 to move focus into the panel. A screen reader hears the link when the panel opens. The panel closes when the caret moves. In a read-only editor the panel shows the target and Copy only.
• Editing. Ctrl+K or Cmd+K, the link control, Insert > Link…, and Edit open the URL field with Apply and Cancel. For an existing link, the panel also shows the target and Copy.

The packaged popup is PptxEditor.HyperLink, with named parts on the toolbar's customization steps:

Every part takes className, asChild, and hidden. A part that you pass as a child replaces the default copy of that part. preset={false} renders only your children. The panel carries data-mode="reading" or data-mode="editing" for your CSS. The display text is not a field: a link applies to the selected text, or to the word at the caret.

useHyperlinkPopup() returns the state (mode, url, href, draft, error, copied, canEdit) and the actions (open, openAtCaret, close, copy, openTarget, beginEdit, setUrl, commitEdit, unlink), for a panel of your own. The link applies to the existing text; there is no setText action. error contains reason text. open(link, anchor) shows the link at the caret: open(null) opens the URL field, and open() opens the link at the caret, or the URL field when there is none. Inside PptxEditor.Root, the hook shares the root's link state. Call it in a panel or a popups.hyperlink renderer. To disable the packaged panel, set popups.hyperlink: false. A mounted custom panel still receives link requests. See Build your own link panel.

Render your panel from popups.hyperlink. A renderer opens for the URL field only. To show reading mode too, register it with definePopup(YourPanel, { reading: true }): a click into linked text then renders it with mode: 'reading'. The renderer also receives HyperlinkPopupProps:

function AcmeLink() {
  return (
    <PptxEditor.HyperLink className="acme-link">
      <PptxEditor.HyperLink.Copy hidden />
      <PptxEditor.HyperLink.Unlink icon={<TrashIcon />} />
    </PptxEditor.HyperLink>
  );
}

const popups: PptxEditorPopups = { hyperlink: definePopup(AcmeLink, { reading: true }) };

In Vue, use PptxEditorHyperLink with the same parts and useHyperlinkPopup(). An action's glyph goes in its icon slot.

Dialog part options

Packaged dialogs expose Header, Title, Body, Footer, Field, Error, Apply, and Cancel. The Background dialog also exposes Reset, which picks the layout's background.

The part's own wiring wins over conflicting props: a stray onClick cannot detach Apply from the dialog.

Draft hooks

The draft hooks are usePageSetupDialog, useBackgroundDialog, useFontDialog, useParagraphDialog, useBulletsAndNumberingDialog, useColumnsDialog, useImageAltTextDialog, and useImagePropertiesDialog. They return values, setValue, errors, isEnabled, apply, and cancel. useBackgroundDialog also returns reset. errors holds translated messages, one for each field. Call the hooks inside the dialog, for your own fields.

Apply validates and commits the draft. A refusal keeps the dialog open with the engine's reason in the Error part. The draft rules live in core (createDialogDraft), so the React and Vue dialogs commit the same way.

OK applies the draft. The Background, Font, Paragraph, Bullets and Numbering, Columns, Alt Text, and Format Picture dialogs commit it as one undo step. The Page setup dialog sends one setSlideSize command when the slide size changed, and reports the appearance through onThemeChange. Cancel discards the draft.

Dialog fields

Page setup fields

Background fields

Paragraph fields

The Paragraph dialog reads the selected paragraphs. A field that the paragraphs disagree on shows "Mixed" and stays as it is unless you change it. OK writes only the fields that changed, as one setParagraphFormat command. A section and each field in it are Field parts, so you can hide one field or the whole section.

Font fields

The Font dialog has two tabs, Font and Character Spacing, and reads the selected text. A field that the text disagrees on shows "Mixed" or a cleared box. OK writes only the fields that changed, as one setFontFormat command. Each field is a Field part, and so are the two sections of the Font tab.

Bullets and numbering fields

The dialog has a Bulleted tab and a Numbered tab. It opens on the tab of the selected paragraphs' list, also when each level has its own bullet. When the paragraphs have no list, or have both kinds, it opens on the tab of the gallery it came from. A field that the paragraphs disagree on shows "Mixed". OK sends one setBulletFormat command for the selected paragraphs, with only the fields that changed. A tab and each field on it are Field parts.

Columns fields

Alt Text fields

OK sends only the fields you changed, as one setAltText command.

On the slide, a picture with a description is an image (role="img") with the description as its name. A screen reader skips a decorative picture and a picture with no description. The slide show exposes the slide the same way: its text, and the alt text of its pictures. When Tab selects an object, a screen reader hears its kind, its name, and its description. An example is "Picture Landscape, A dusk sky over a lake, selected".

Format Picture fields

OK sends only the values you changed, as one setImageProperties command. The draft fields are width, height, lockAspect, rotation, cropLeft, cropTop, cropRight, and cropBottom.

Dialog styling

Dialogs render outside PptxEditor.Viewport. Each dialog element carries .pptx-dialog and its own .pptx-editor scope, and dark with a dark color mode. Scope your theme on an element around PptxEditor.Root, or pass a className through the renderer. See Appearance for the dialog tokens.

Popup lifetime

Keep the renderer's session props (open and onClose) when you wrap a popup. A dialog belongs to the document it opened on. It closes when the editor opens another document, so a draft never edits the replacement. The Alt Text and Format Picture dialogs also belong to the object they opened on. They close when the selection moves to another object or the object is removed. The dialog unmounts when it closes, so the next opening starts from the document again.

The packaged dialog surface keeps focus inside, closes on Escape, and returns focus to the element that opened it. A separate application modal must keep those behaviors.

React and Vue reference

The Vue adapter has the same registry keys and the same packaged dialogs: Page setup, Background, Font, Paragraph, Bullets and Numbering, Columns, Alt Text, and Format Picture. It also has the link popup (HyperlinkPopup) and the find bar (PptxEditorFindBar). Each dialog has the same named parts as its React twin, and a registry entry receives open and onClose. Build a Vue entry with h, for example h(PageSetupDialog, props, () => [h(PageSetupDialog.Field, { name: 'substitutes', hidden: true })]).

Vue also has useFontFormat, useParagraphFormat, and useBulletFormat for your own dialogs. The Vue toolbar draws the controls that open the picture dialogs, as React's does. To open a dialog from your own control, call useEditorDialog.

See also

• Dialogs
• Appearance
• @pptx-editor.dev/react API report, for PptxEditorPopups, the dialog props, and the draft hook types