CORE

XML Components

Base classes and helpers for building OOXML XML element trees

All OOXML elements in @office-open/docx and @office-open/pptx are built on XmlComponent. This page covers the core building blocks.

XmlComponent

The primary base class for OOXML elements. Each element wraps an XML tag name and manages child elements.

import { XmlComponent } from "@office-open/core";

class MyElement extends XmlComponent {
    constructor() {
        super("w:myElement");
    }
}

Use root to push child elements during construction:

import { XmlComponent, onOffObj } from "@office-open/core";

class BoldElement extends XmlComponent {
    constructor() {
        super("w:b");
        this.root.push(onOffObj("w:bCs", true));
    }
}

Element Builders

Zero-allocation helper functions that return plain objects. Prefer these over the deprecated element classes.

Function	Produces	Example
`onOffObj(name, val?)`	Boolean on/off element	`onOffObj("w:b", true)`
`hpsMeasureObj(name, val)`	Half-point measurement	`hpsMeasureObj("w:sz", 24)`
`stringValObj(name, val)`	String value attribute	`stringValObj("w:val", "hello")`
`numberValObj(name, val)`	Numeric value attribute	`numberValObj("w:count", 3)`
`stringEnumValObj(name, val)`	String enum value	`stringEnumValObj("w:align", "center")`
`stringContainerObj(name, val)`	Element wrapping text	`stringContainerObj("w:t", "Hello")`

BuilderElement

A flexible element with explicit attribute and child configuration:

import { BuilderElement } from "@office-open/core";

const el = new BuilderElement({
    name: "w:spacing",
    attributes: { before: 240, after: 120 },
    children: [],
});

Attribute Components

XmlAttributeComponent

Maps TypeScript properties to XML attribute names:

import { XmlAttributeComponent, XmlComponent } from "@office-open/core";

interface ISpacingAttributes {
    readonly before?: number;
    readonly after?: number;
}

class SpacingAttributes extends XmlAttributeComponent<ISpacingAttributes> {
    protected readonly xmlKeys = { before: "w:before", after: "w:after" };
}

NextAttributeComponent

Uses explicit key-value pairs without name mapping:

import { NextAttributeComponent } from "@office-open/core";

class MyAttributes extends NextAttributeComponent({
    size: "w:sz",
    color: "w:color",
}) {}

ImportedXmlComponent

Wraps raw XML content for embedding into the document tree:

import { ImportedXmlComponent } from "@office-open/core";

const imported = ImportedXmlComponent.fromXmlString(
    '<w:pPr xmlns:w="..."><w:jc w:val="center"/></w:pPr>',
);

convertToXmlComponent

Converts a parsed Element (from @office-open/xml) into an XmlComponent tree:

import { convertToXmlComponent } from "@office-open/core";
import { parse } from "@office-open/xml";

const element = parse("<w:p><w:r><w:t>Hello</w:t></w:r></w:p>");
const component = convertToXmlComponent(element);

Utility Functions

wrapEl

Wraps a child component in a named element:

import { wrapEl } from "@office-open/core";

const wrapped = wrapEl("w:rPr", someChildComponent);

Other Components

Component	Description
`IgnoreIfEmptyXmlComponent`	Excluded from XML output when empty
`InitializableXmlComponent`	Can be initialized from another component instance
`EmptyElement`	Represents an empty XML element

Edit this pageorReport an issue

@office-open/core

Shared XML components, value validation, formatting, and unit converters

Values and Validation

Runtime validation and type conversion for OOXML specification value types