Capture a selection as Word XML

Use doc.selection.extractOoxml() when your application needs a copy of part of a document in Word's XML format (OOXML). For example, you can save a selected clause for later review or pass its original Word markup to another document workflow. The result includes the selected content and the supporting DOCX parts it refers to, such as images, styles, numbering, and hyperlinks.

This is a read operation. It does not change the open document or create an undo step.

Capture what the user selected

With a mounted v2 editor, call the API while the user's selection is still active. superdoc below is your existing SuperDoc instance; see the Editor quickstart to create one.

async function captureSelection() {
  const doc = superdoc.activeEditor?.doc;
  if (!doc) throw new Error('The active document is unavailable.');

  const capture = await doc.selection.extractOoxml({ selection: 'current' });
  const savedCapture = JSON.stringify(capture);
  return savedCapture;
}

Call captureSelection() before opening a dialog or moving focus away from the editor. Keep the whole result when saving it: fragment.xml alone does not contain every supporting part needed to interpret the selection. The call requires a nonempty selection.

Selections can include part of a paragraph, multiple paragraphs, lists, tables, and content in a table cell, header, or footer. The capture also preserves relevant markup for hyperlinks, fields, drawings, notes, comments, tracked changes, and content controls.

Capture a saved location

You can pass a selection address with at instead of reading the live editor selection. This also works in a headless document workflow:

const capture = await doc.selection.extractOoxml({ at: savedSelection });

savedSelection is a SelectionTarget previously obtained from the Document API. The call reads the content currently at that address. Edits elsewhere do not invalidate the address solely because the document revision changed; the address still needs to resolve in the current document.

For an explicitly addressed rectangle of table cells, pass the table ID and zero-based cell coordinates:

const capture = await doc.selection.extractOoxml({
  at: {
    kind: 'tableCells',
    tableId,
    start: { rowIndex: 0, columnIndex: 0 },
    end: { rowIndex: 2, columnIndex: 1 },
  },
});

Here tableId is the ID of the table in the document. The start and end cells are included.

Read the result

Table captures also include fragment.table, which describes the selected cells, grid positions, spans, and vertical merges. context.tableMerges supplies merge information from above the selected rows when needed, without including those cells' visible content.

evaluatedRevision tells you which document revision was read. It is information about the capture, not a requirement for a later read. The API has no expectedRevision input.

Using the captured XML later

The result is a capture, not a DOCX file. Pass the whole manifest to doc.insert({ target, capture }) or doc.replace({ target, capture }) for a native copy. These operations import supporting parts and remap paragraph, review, drawing and relationship identities. The copy route supports bounded ordinary paragraph/run, hyperlink, image, local text-revision/comment and table markup. Unsupported fields, controls, notes, moves, structural revisions, malformed nesting or incomplete dependencies are rejected atomically. Broader extraction support does not imply that every capture is currently insertable.

For exact same-session restoration of a complete direct body paragraph, heading or list item, add retain: true to its before/after node-edge selection. The result includes an opaque snapshotId, and source.packageRevision identifies the package read for committed review UI pairing. Use the handle with doc.replace({ target, snapshotId }, { replaceMode: 'contents', expectedSnapshotId, changeMode: 'direct' }); release unused handles through doc.selection.releaseSnapshot({ snapshotId }). Handles are not portable across documents or serialized sessions. See paragraph alternatives for the complete lifecycle and restrictions.

The existing contentControls.replaceContent({ format: 'ooxml' }) remains an inline content-control operation with its own target semantics.

Insert and replace complete equations

Insert a complete Office Math equation through the native OOXML route:

const doc = superdoc.activeEditor.doc;
const current = await doc.selection.current({});
if (!current.selectionTarget) throw new Error('Choose an insertion location.');

const result = await doc.insert(
  {
    target: current.selectionTarget,
    type: 'ooxml',
    value: '<m:oMath><m:r><m:t>x+1</m:t></m:r></m:oMath>',
    namespaces: { m: 'http://schemas.openxmlformats.org/officeDocument/2006/math' },
  },
  { changeMode: 'direct' },
);

Use a collapsed selection for insertion. To replace an equation, select the complete equation and pass its current selection target to doc.replace() with type: 'ooxml' and the replacement XML. Both <m:oMath> and <m:oMathPara> roots are accepted. These mutations use the normal undo history without remounting the editor.

The browser treats each equation as one caret unit. Users can type beside it, delete the complete equation with adjacent Backspace or Delete, and press Enter after it. Editing part of an equation is unsupported.

Tracked authoring and shared authoring accept one complete equation at an explicit text selection within one paragraph: a collapsed selection inserts it, and a selection covering a complete equation replaces it. Use { changeMode: 'tracked' } to retain author attribution and review decisions. Shared block placement, node-edge targets, partial equations, arbitrary native XML and captured package dependencies return a failure before applying a mutation. Direct edits outside collaboration retain their existing block-target behavior.

Internal clipboard fragments preserve complete inline and display equations as editable native math. External Word HTML can supply a complete Office Math subtree; MathML, partial equations and unsupported nested controls are refused. A standalone { kind: 'math', omml } clipboard inline requires self-contained Office Math namespace declarations. Equation paste uses normal history and can participate in tracked and shared authoring.

Imported Word documents can retain pending revisions inside equation runs for display, review decisions and reopening. Fresh native writes and clipboard math inputs require equation XML without embedded revision markup; unsupported revision-rich inputs are refused before mutation.

Your application supplies its equation-entry UI and converts LaTeX to Transitional OMML before insertion. Native Markdown math input and recovery of the original LaTeX from OMML are not provided.

An empty selection, an address that no longer resolves, or invalid source data produces a structured validation error. Captures above the resource limits fail with RESOURCE_LIMIT and return no partial result: one referenced part can be at most 64 MiB, encoded dependency source bytes can total at most 128 MiB, and a capture can include at most 1,024 relationships.

See the generated selection.extractOoxml reference for the complete input, result, and error types.