Hooks

Call editor-state hooks inside PptxEditor.Root. The packaged <PptxEditor> provides that root for its children.

usePptxSource and useFonts prepare input for the root, so you can call them in the parent component.

Connect a command button

This button runs a toolbar command and shows why the command cannot run:

import { useEditorCommand, useTranslation } from '@pptx-editor.dev/react';
import { translateKeyOrText } from '@pptx-editor.dev/core/editor';

export function BoldButton() {
  const bold = useEditorCommand('text.bold');
  const { t } = useTranslation();
  const reason = bold.disabledReason;
  return (
    <button
      type="button"
      aria-disabled={!bold.isEnabled || undefined}
      aria-pressed={bold.isActive}
      aria-label={t('toolbar.bold')}
      title={reason ? translateKeyOrText(t, reason) : t('toolbar.bold')}
      onMouseDown={(event) => event.preventDefault()}
      onClick={() => bold.execute()}
    >
      B
    </button>
  );
}

useEditorCommand(slot: ChromeSlotId): UseEditorCommandReturn takes a slot identifier from the toolbar slot reference.

The types in these signatures, such as ChromeSlotId, CommandResult, EditorSnapshot, and PptxEditorInstance, are exported from @pptx-editor.dev/react. You do not need an import from @pptx-editor.dev/core to type your handlers.

Read state

useEditorState(selector, isEqual?) returns one slice of the editor snapshot. The component renders again only when the slice changes:

import { useEditorState } from '@pptx-editor.dev/react';

export function SlideCounter() {
  const current = useEditorState((s) => s.currentSlide);
  const total = useEditorState((s) => s.slides.length);
  return (
    <span>
      {current + 1} / {total}
    </span>
  );
}

Pass a comparator for an object slice. Common fields include status, slides, currentSlide, selection, format, mode, canUndo, canRedo, presentationView, and lastRejection.

usePptxEditor

Use the instance for actions and one-time reads:

import { usePptxEditor } from '@pptx-editor.dev/react';

export function SaveButton({ upload }: { upload: (bytes: Uint8Array) => Promise<void> }) {
  const editor = usePptxEditor();
  return (
    <button
      disabled={!editor}
      onClick={() => {
        const saved = editor?.save();
        if (saved) void upload(saved);
      }}
    >
      Save
    </button>
  );
}

A direct snapshot() call does not subscribe the component. Use useEditorState for values that you render.

Choose a hook

Formatting

Slides and panes

Dialogs, menus, and notices

Fonts

Open a presentation

usePptxSource(source, { fonts?, fetchOptions? }) loads bytes from a URL and resolves fonts. It cancels stale fetches when the source changes or the component unmounts:

import { PptxEditor, usePptxSource } from '@pptx-editor.dev/react';
import { packagedFonts } from '@docx-editor.dev/fonts';

export function Deck({ url }: { url: string }) {
  const { document, fonts, error } = usePptxSource(url, { fonts: packagedFonts() });
  if (error) return <p>{error.message}</p>;
  return <PptxEditor document={document} fonts={fonts} />;
}

Eager fonts (a value, a promise, or a zero-argument loader) hold the deck back until they settle, so the slides lay out once. They hold it for at most 2 seconds. Fonts that settle later still apply, and the slides lay out again. An on-demand resolver (packagedFonts(), googleFonts()) needs the parsed deck, so the bytes go through at once, and fonts is one resolver for the life of the hook.

A string source is always a URL, fetched as you wrote it. Check a URL from user input first. When no bytes arrive for 10 seconds, the download stops and error is a TimeoutError. A slow download that keeps sending bytes finishes.

The download also stops when the file is longer than 528 MiB, the longest file the editor opens. The hook checks the Content-Length header before the body arrives, and the byte count while it downloads. In both cases, error is a RangeError.

Build your own chrome

Use these hooks to connect your controls to the editor.

Zoom

useZoom(): UseZoomResult reads and sets the slide zoom. This control replaces the zoom pill:

import { useZoom } from '@pptx-editor.dev/react';

export function ZoomControl() {
  const { zoom, isFit, fit, zoomIn, zoomOut, canZoomIn, canZoomOut } = useZoom();
  return (
    <div role="group" aria-label="Zoom">
      <button onClick={zoomOut} disabled={!canZoomOut} aria-label="Zoom out">
        -
      </button>
      <span>{Math.round(zoom * 100)}%</span>
      <button onClick={zoomIn} disabled={!canZoomIn} aria-label="Zoom in">
        +
      </button>
      <button onClick={fit} aria-pressed={isFit}>
        Fit
      </button>
    </div>
  );
}

Use fit() to fit the whole slide. Use setZoom() for a fixed zoom level.

Events

useEditorEvent(event, handler): void calls handler each time the event occurs, while the component is mounted:

import { useEditorEvent } from '@pptx-editor.dev/react';

export function RefusalToast({ show }: { show: (text: string) => void }) {
  useEditorEvent('rejection', (rejection) => show(rejection.reason));
  return null;
}

The events come from the editor's one subscription. Outside the adapters, onEditorEvent(editor, event, handler) from @pptx-editor.dev/core/editor gives the same events and returns the unsubscribe function. The PptxEditorEvents type lists the events.

Other hooks

Find, caret, and undo steps

import { useEditorValueCommand, useHistoryGroup } from '@pptx-editor.dev/react';

export function SizeSlider() {
  const group = useHistoryGroup({ kind: 'range' });
  const size = useEditorValueCommand('font.size');
  return (
    <input
      type="range"
      aria-label="Font size"
      min={8}
      max={96}
      ref={group.ref}
      onChange={(e) => size.execute(Number(e.target.value), group.options())}
    />
  );
}

Labels

Toolbar, Menu, ContextMenu, SlideRail, StatusBar, FindBar, OpenFailure, FontNotice, and EditNotice take a t prop. With it, the compound and its parts take every label from your function. The dialogs take their labels from the root's locale.

Search selection

Find shows the active match as the slide selection. useDocumentSearch does not expose a named text highlight layer.

Apply a value

useEditorValueCommand(slot) reads the value of a value slot and applies a new one, with the slot's type from ToolbarValueMap. This slider sets the font size:

import { useEditorValueCommand } from '@pptx-editor.dev/react';

export function FontSizeSlider() {
  const size = useEditorValueCommand('font.size');
  return (
    <label>
      {size.value === null ? 'Mixed' : `${size.value} pt`}
      <input
        type="range"
        min={8}
        max={96}
        value={size.value ?? 18}
        disabled={!size.isEnabled}
        onChange={(event) => {
          const result = size.execute(Number(event.target.value));
          if (!result.ok) console.info(result.reason);
        }}
      />
    </label>
  );
}

font.size takes points, or { step: 1 } and { step: -1 } for one step of the size list. null means mixed or unavailable.

The two hooks return different results from execute: useEditorCommand returns a boolean, because a toolbar button only needs to know if the command ran, and useEditorValueCommand returns the CommandResult, because a value control shows why the engine refused a value.

To make the values of one slider drag one undo step, pass { historyGroup } from editor.beginHistoryGroup(). See Group a slider or a stepper.

Limits

• Call hooks inside PptxEditor.Root. Outside it, usePptxEditor() returns null.
• canUndo reports undo availability, not unsaved changes. Track saves yourself.
• Dialog draft hooks read a draft. They do not open the dialog; use useEditorDialog(key) for that.
• disabledReason can be a translation key. Show it with translateKeyOrText(t, reason) from @pptx-editor.dev/core/editor.

See also

• React composition
• Toolbar
• Undo history