Word.Paragraph class

Gets or sets the alignment for a paragraph. The value can be 'left', 'centered', 'right', or 'justified'.

[ API set: WordApi 1.1 ]

alignment: Word.Alignment | "Mixed" | "Unknown" | "Left" | "Centered" | "Right" | "Justified";

Property Value

Examples

await Word.run(async (context) => {
  // Centers last paragraph alignment.
  context.document.body.paragraphs.getLast().alignment = "Centered";

  await context.sync();
});

Gets the collection of content control objects in the paragraph. Read-only.

[ API set: WordApi 1.1 ]

readonly contentControls: Word.ContentControlCollection;

Property Value

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

Gets or sets the value, in points, for a first line or hanging indent. Use a positive value to set a first-line indent, and use a negative value to set a hanging indent.

[ API set: WordApi 1.1 ]

firstLineIndent: number;

Property Value

Gets the text format of the paragraph. Use this to get and set font name, size, color, and other properties. Read-only.

[ API set: WordApi 1.1 ]

readonly font: Word.Font;

Property Value

Gets the collection of InlinePicture objects in the paragraph. The collection does not include floating images. Read-only.

[ API set: WordApi 1.1 ]

readonly inlinePictures: Word.InlinePictureCollection;

Property Value

Indicates the paragraph is the last one inside its parent body. Read-only.

[ API set: WordApi 1.3 ]

readonly isLastParagraph: boolean;

Property Value

Checks whether the paragraph is a list item. Read-only.

[ API set: WordApi 1.3 ]

readonly isListItem: boolean;

Property Value

Gets or sets the left indent value, in points, for the paragraph.

[ API set: WordApi 1.1 ]

leftIndent: number;

Property Value

Examples

await Word.run(async (context) => {
  // Indents the first paragraph.
  context.document.body.paragraphs.getFirst().leftIndent = 75; //units = points

  return context.sync();
});

Gets or sets the line spacing, in points, for the specified paragraph. In the Word UI, this value is divided by 12.

[ API set: WordApi 1.1 ]

lineSpacing: number;

Property Value

Examples

await Word.run(async (context) => {
  // Adjusts line spacing.
  context.document.body.paragraphs.getFirst().lineSpacing = 20;

  await context.sync();
});

Gets or sets the amount of spacing, in grid lines, after the paragraph.

[ API set: WordApi 1.1 ]

lineUnitAfter: number;

Property Value

Gets or sets the amount of spacing, in grid lines, before the paragraph.

[ API set: WordApi 1.1 ]

lineUnitBefore: number;

Property Value

Gets the List to which this paragraph belongs. Throws an error if the paragraph is not in a list. Read-only.

[ API set: WordApi 1.3 ]

readonly list: Word.List;

Property Value

Gets the ListItem for the paragraph. Throws an error if the paragraph is not part of a list. Read-only.

[ API set: WordApi 1.3 ]

readonly listItem: Word.ListItem;

Property Value

Gets the ListItem for the paragraph. Returns a null object if the paragraph is not part of a list. Read-only.

[ API set: WordApi 1.3 ]

readonly listItemOrNullObject: Word.ListItem;

Property Value

Gets the List to which this paragraph belongs. Returns a null object if the paragraph is not in a list. Read-only.

[ API set: WordApi 1.3 ]

readonly listOrNullObject: Word.List;

Property Value

Gets or sets the outline level for the paragraph.

[ API set: WordApi 1.1 ]

outlineLevel: number;

Property Value

Gets the parent body of the paragraph. Read-only.

[ API set: WordApi 1.3 ]

readonly parentBody: Word.Body;

Property Value

Gets the content control that contains the paragraph. Throws an error if there isn't a parent content control. Read-only.

[ API set: WordApi 1.1 ]

readonly parentContentControl: Word.ContentControl;

Property Value

Gets the content control that contains the paragraph. Returns a null object if there isn't a parent content control. Read-only.

[ API set: WordApi 1.3 ]

readonly parentContentControlOrNullObject: Word.ContentControl;

Property Value

Gets the table that contains the paragraph. Throws an error if it is not contained in a table. Read-only.

[ API set: WordApi 1.3 ]

readonly parentTable: Word.Table;

Property Value

Gets the table cell that contains the paragraph. Throws an error if it is not contained in a table cell. Read-only.

[ API set: WordApi 1.3 ]

readonly parentTableCell: Word.TableCell;

Property Value

Gets the table cell that contains the paragraph. Returns a null object if it is not contained in a table cell. Read-only.

[ API set: WordApi 1.3 ]

readonly parentTableCellOrNullObject: Word.TableCell;

Property Value

Gets the table that contains the paragraph. Returns a null object if it is not contained in a table. Read-only.

[ API set: WordApi 1.3 ]

readonly parentTableOrNullObject: Word.Table;

Property Value

Gets or sets the right indent value, in points, for the paragraph.

[ API set: WordApi 1.1 ]

rightIndent: number;

Property Value

Gets or sets the spacing, in points, after the paragraph.

[ API set: WordApi 1.1 ]

spaceAfter: number;

Property Value

Examples

await Word.run(async (context) => {
  // Adjust space between paragraphs.
  context.document.body.paragraphs.getFirst().spaceAfter = 20;

  await context.sync();
});

Gets or sets the spacing, in points, before the paragraph.

[ API set: WordApi 1.1 ]

spaceBefore: number;

Property Value

Gets or sets the style name for the paragraph. Use this property for custom styles and localized style names. To use the built-in styles that are portable between locales, see the "styleBuiltIn" property.

[ API set: WordApi 1.1 ]

style: string;

Property Value

Gets or sets the built-in style name for the paragraph. Use this property for built-in styles that are portable between locales. To use custom styles or localized style names, see the "style" property.

[ API set: WordApi 1.3 ]

styleBuiltIn: Word.Style | "Other" | "Normal" | "Heading1" | "Heading2" | "Heading3" | "Heading4" | "Heading5" | "Heading6" | "Heading7" | "Heading8" | "Heading9" | "Toc1" | "Toc2" | "Toc3" | "Toc4" | "Toc5" | "Toc6" | "Toc7" | "Toc8" | "Toc9" | "FootnoteText" | "Header" | "Footer" | "Caption" | "FootnoteReference" | "EndnoteReference" | "EndnoteText" | "Title" | "Subtitle" | "Hyperlink" | "Strong" | "Emphasis" | "NoSpacing" | "ListParagraph" | "Quote" | "IntenseQuote" | "SubtleEmphasis" | "IntenseEmphasis" | "SubtleReference" | "IntenseReference" | "BookTitle" | "Bibliography" | "TocHeading" | "TableGrid" | "PlainTable1" | "PlainTable2" | "PlainTable3" | "PlainTable4" | "PlainTable5" | "TableGridLight" | "GridTable1Light" | "GridTable1Light_Accent1" | "GridTable1Light_Accent2" | "GridTable1Light_Accent3" | "GridTable1Light_Accent4" | "GridTable1Light_Accent5" | "GridTable1Light_Accent6" | "GridTable2" | "GridTable2_Accent1" | "GridTable2_Accent2" | "GridTable2_Accent3" | "GridTable2_Accent4" | "GridTable2_Accent5" | "GridTable2_Accent6" | "GridTable3" | "GridTable3_Accent1" | "GridTable3_Accent2" | "GridTable3_Accent3" | "GridTable3_Accent4" | "GridTable3_Accent5" | "GridTable3_Accent6" | "GridTable4" | "GridTable4_Accent1" | "GridTable4_Accent2" | "GridTable4_Accent3" | "GridTable4_Accent4" | "GridTable4_Accent5" | "GridTable4_Accent6" | "GridTable5Dark" | "GridTable5Dark_Accent1" | "GridTable5Dark_Accent2" | "GridTable5Dark_Accent3" | "GridTable5Dark_Accent4" | "GridTable5Dark_Accent5" | "GridTable5Dark_Accent6" | "GridTable6Colorful" | "GridTable6Colorful_Accent1" | "GridTable6Colorful_Accent2" | "GridTable6Colorful_Accent3" | "GridTable6Colorful_Accent4" | "GridTable6Colorful_Accent5" | "GridTable6Colorful_Accent6" | "GridTable7Colorful" | "GridTable7Colorful_Accent1" | "GridTable7Colorful_Accent2" | "GridTable7Colorful_Accent3" | "GridTable7Colorful_Accent4" | "GridTable7Colorful_Accent5" | "GridTable7Colorful_Accent6" | "ListTable1Light" | "ListTable1Light_Accent1" | "ListTable1Light_Accent2" | "ListTable1Light_Accent3" | "ListTable1Light_Accent4" | "ListTable1Light_Accent5" | "ListTable1Light_Accent6" | "ListTable2" | "ListTable2_Accent1" | "ListTable2_Accent2" | "ListTable2_Accent3" | "ListTable2_Accent4" | "ListTable2_Accent5" | "ListTable2_Accent6" | "ListTable3" | "ListTable3_Accent1" | "ListTable3_Accent2" | "ListTable3_Accent3" | "ListTable3_Accent4" | "ListTable3_Accent5" | "ListTable3_Accent6" | "ListTable4" | "ListTable4_Accent1" | "ListTable4_Accent2" | "ListTable4_Accent3" | "ListTable4_Accent4" | "ListTable4_Accent5" | "ListTable4_Accent6" | "ListTable5Dark" | "ListTable5Dark_Accent1" | "ListTable5Dark_Accent2" | "ListTable5Dark_Accent3" | "ListTable5Dark_Accent4" | "ListTable5Dark_Accent5" | "ListTable5Dark_Accent6" | "ListTable6Colorful" | "ListTable6Colorful_Accent1" | "ListTable6Colorful_Accent2" | "ListTable6Colorful_Accent3" | "ListTable6Colorful_Accent4" | "ListTable6Colorful_Accent5" | "ListTable6Colorful_Accent6" | "ListTable7Colorful" | "ListTable7Colorful_Accent1" | "ListTable7Colorful_Accent2" | "ListTable7Colorful_Accent3" | "ListTable7Colorful_Accent4" | "ListTable7Colorful_Accent5" | "ListTable7Colorful_Accent6";

Property Value

Gets the level of the paragraph's table. It returns 0 if the paragraph is not in a table. Read-only.

[ API set: WordApi 1.3 ]

readonly tableNestingLevel: number;

Property Value

Gets the text of the paragraph. Read-only.

[ API set: WordApi 1.1 ]

readonly text: string;

Property Value

Examples

await Word.run(async (context) => {
  // The collection of paragraphs of the current selection returns the full paragraphs contained in it.
  let paragraph = context.document.getSelection().paragraphs.getFirst();
  paragraph.load("text");

  await context.sync();
  console.log(paragraph.text);
});

Lets the paragraph join an existing list at the specified level. Fails if the paragraph cannot join the list or if the paragraph is already a list item.

[ API set: WordApi 1.3 ]

attachToList(listId: number, level: number): Word.List;

Parameters

Returns

Clears the contents of the paragraph object. The user can perform the undo operation on the cleared content.

[ API set: WordApi 1.1 ]

clear(): void;

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the paragraphs collection.
    var paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for all of the paragraphs.
    context.load(paragraphs, 'style');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {

        // Queue a command to clear the contents of the first paragraph.
        paragraphs.items[0].clear();

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            console.log('Cleared the contents of the first paragraph.');
        });
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

Deletes the paragraph and its content from the document.

[ API set: WordApi 1.1 ]

delete(): void;

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the paragraphs collection.
    var paragraphs = context.document.body.paragraphs;

    // Queue a command to load the text property for all of the paragraphs.
    context.load(paragraphs, 'text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {

        // Queue a command to delete the first paragraph.
        paragraphs.items[0].delete();

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            console.log('Deleted the first paragraph.');
        });
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

Moves this paragraph out of its list, if the paragraph is a list item.

[ API set: WordApi 1.3 ]

detachFromList(): void;

Returns

Gets an HTML representation of the paragraph object. When rendered in a web page or HTML viewer, the formatting will be a close, but not exact, match for of the formatting of the document. This method does not return the exact same HTML for the same document on different platforms (Windows, Mac, Word for the web, etc.). If you need exact fidelity, or consistency across platforms, use Paragraph.getOoxml() and convert the returned XML to HTML.

[ API set: WordApi 1.1 ]

getHtml(): OfficeExtension.ClientResult<string>;

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the paragraphs collection.
    var paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for all of the paragraphs.
    context.load(paragraphs, 'style');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {

        // Queue a a set of commands to get the HTML of the first paragraph.
        var html = paragraphs.items[0].getHtml();

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            console.log('Paragraph HTML: ' + html.value);
        });
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

Gets the next paragraph. Throws an error if the paragraph is the last one.

[ API set: WordApi 1.3 ]

getNext(): Word.Paragraph;

Returns

Gets the next paragraph. Returns a null object if the paragraph is the last one.

[ API set: WordApi 1.3 ]

getNextOrNullObject(): Word.Paragraph;

Returns

Gets the Office Open XML (OOXML) representation of the paragraph object.

[ API set: WordApi 1.1 ]

getOoxml(): OfficeExtension.ClientResult<string>;

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the paragraphs collection.
    var paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for the top 2 paragraphs.
    context.load(paragraphs, {select: 'style', top: 2} );

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {

        // Queue a a set of commands to get the OOXML of the first paragraph.
        var ooxml = paragraphs.items[0].getOoxml();

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            console.log('Paragraph OOXML: ' + ooxml.value);
        });
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

Gets the previous paragraph. Throws an error if the paragraph is the first one.

[ API set: WordApi 1.3 ]

getPrevious(): Word.Paragraph;

Returns

Gets the previous paragraph. Returns a null object if the paragraph is the first one.

[ API set: WordApi 1.3 ]

getPreviousOrNullObject(): Word.Paragraph;

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the paragraphs collection.
    var paragraphs = context.document.body.paragraphs;

    // Queue a command to load the text property for all of the paragraphs.
    context.load(paragraphs, 'text');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {

        // Queue commands to create a proxy object for the next-to-last paragraph.
        var indexOfLastParagraph = paragraphs.items.length - 1;
        var precedingParagraph = paragraphs.items[indexOfLastParagraph].getPreviousOrNullObject();

        // Queue a command to load the text of the preceding paragraph.
        context.load(precedingParagraph, 'text');

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            if (precedingParagraph.isNullObject) {
                console.log('There are no paragraphs before the current one.');
            } else {
                console.log('The preceding paragraph is: ' + precedingParagraph.text);
            }
        });
    });
}).catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

Gets the whole paragraph, or the starting or ending point of the paragraph, as a range.

[ API set: WordApi 1.3 ]

getRange(rangeLocation?: Word.RangeLocation): Word.Range;

Parameters

Returns

Gets the whole paragraph, or the starting or ending point of the paragraph, as a range.

[ API set: WordApi 1.3 ]

getRange(rangeLocationString?: "Whole" | "Start" | "End" | "Before" | "After" | "Content"): Word.Range;

Parameters

Returns

Gets the text ranges in the paragraph by using punctuation marks and/or other ending marks.

[ API set: WordApi 1.3 ]

getTextRanges(endingMarks: string[], trimSpacing?: boolean): Word.RangeCollection;

Parameters

Returns

Inserts a break at the specified location in the main document.

[ API set: WordApi 1.1 ]

insertBreak(breakType: Word.BreakType, insertLocation: Word.InsertLocation): void;

Parameters

Returns

Examples

Word.run(async (context) => {
  context.document.body.paragraphs.getFirst().insertBreak(Word.BreakType.line, "After");

  await context.sync();
  console.log("success");
});

await Word.run(async (context) => {
  context.document.body.paragraphs.getFirst().insertBreak(Word.BreakType.page, "After");

  await context.sync();
  console.log("success");
});

Inserts a break at the specified location in the main document.

[ API set: WordApi 1.1 ]

insertBreak(breakTypeString: "Page" | "Next" | "SectionNext" | "SectionContinuous" | "SectionEven" | "SectionOdd" | "Line", insertLocation: "Before" | "After" | "Start" | "End" | "Replace"): void;

Parameters

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the paragraphs collection.
    var paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for the top 2 paragraphs.
    // We never perform an empty load. We always must request a property.
    context.load(paragraphs, {select: 'style', top: 2} );

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {

        // Queue a command to get the first paragraph.
        var paragraph = paragraphs.items[0];

        // Queue a command to insert a page break after the first paragraph.
        paragraph.insertBreak('page', 'After');

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            console.log('Inserted a page break after the paragraph.');
        });
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

Wraps the paragraph object with a rich text content control.

[ API set: WordApi 1.1 ]

insertContentControl(): Word.ContentControl;

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the paragraphs collection.
    var paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for the top 2 paragraphs.
    // We never perform an empty load. We always must request a property.
    context.load(paragraphs, {select: 'style', top: 2} );

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {

        // Queue a command to get the first paragraph.
        var paragraph = paragraphs.items[0];

        // Queue a command to wrap the first paragraph in a rich text content control.
        paragraph.insertContentControl();

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            console.log('Wrapped the first paragraph in a content control.');
        });
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

Inserts a document into the paragraph at the specified location.

[ API set: WordApi 1.1 ]

insertFileFromBase64(base64File: string, insertLocation: Word.InsertLocation): Word.Range;

Parameters

Returns

Inserts a document into the paragraph at the specified location.

[ API set: WordApi 1.1 ]

insertFileFromBase64(base64File: string, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace"): Word.Range;

Parameters

Returns

Inserts HTML into the paragraph at the specified location.

[ API set: WordApi 1.1 ]

insertHtml(html: string, insertLocation: Word.InsertLocation): Word.Range;

Parameters

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the paragraphs collection.
    var paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for the top 2 paragraphs.
    // We never perform an empty load. We always must request a property.
    context.load(paragraphs, {select: 'style', top: 2} );

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {

        // Queue a command to get the first paragraph.
        var paragraph = paragraphs.items[0];

        // Queue a command to insert HTML content at the end of the first paragraph.
        paragraph.insertHtml('<strong>Inserted HTML.</strong>', Word.InsertLocation.end);

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            console.log('Inserted HTML content at the end of the first paragraph.');
        });
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

Inserts HTML into the paragraph at the specified location.

[ API set: WordApi 1.1 ]

insertHtml(html: string, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace"): Word.Range;

Parameters

Returns

Inserts a picture into the paragraph at the specified location.

[ API set: WordApi 1.1 ]

insertInlinePictureFromBase64(base64EncodedImage: string, insertLocation: Word.InsertLocation): Word.InlinePicture;

Parameters

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the paragraphs collection.
    var paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for all of the paragraphs.
    context.load(paragraphs, 'style');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {

        // Queue a command to get the first paragraph.
        var paragraph = paragraphs.items[0];

        var b64encodedImg = "iVBORw0KGgoAAAANSUhEUgAAAB4AAAANCAIAAAAxEEnAAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACFSURBVDhPtY1BEoQwDMP6/0+XgIMTBAeYoTqso9Rkx1zG+tNj1H94jgGzeNSjteO5vtQQuG2seO0av8LzGbe3anzRoJ4ybm/VeKEerAEbAUpW4aWQCmrGFWykRzGBCnYy2ha3oAIq2MloW9yCCqhgJ6NtcQsqoIKdjLbFLaiACnYyf2fODbrjZcXfr2F4AAAAAElFTkSuQmCC";

        // Queue a command to insert a base64 encoded image at the beginning of the first paragraph.
        paragraph.insertInlinePictureFromBase64(b64encodedImg, Word.InsertLocation.start);

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            console.log('Added an image to the first paragraph.');
        });
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

Inserts a picture into the paragraph at the specified location.

[ API set: WordApi 1.1 ]

insertInlinePictureFromBase64(base64EncodedImage: string, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace"): Word.InlinePicture;

Parameters

Returns

Inserts OOXML into the paragraph at the specified location.

[ API set: WordApi 1.1 ]

insertOoxml(ooxml: string, insertLocation: Word.InsertLocation): Word.Range;

Parameters

Returns

Inserts OOXML into the paragraph at the specified location.

[ API set: WordApi 1.1 ]

insertOoxml(ooxml: string, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace"): Word.Range;

Parameters

Returns

Inserts a paragraph at the specified location.

[ API set: WordApi 1.1 ]

insertParagraph(paragraphText: string, insertLocation: Word.InsertLocation): Word.Paragraph;

Parameters

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the paragraphs collection.
    var paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for the top 2 paragraphs.
    // We never perform an empty load. We always must request a property.
    context.load(paragraphs, {select: 'style', top: 2} );

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {

        // Queue a command to get the first paragraph.
        var paragraph = paragraphs.items[0];

        // Queue a command to insert the paragraph after the current paragraph.
        paragraph.insertParagraph('Content of a new paragraph', Word.InsertLocation.after);

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            console.log('Inserted a new paragraph at the end of the first paragraph.');
        });
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

await Word.run(async (context) => {
  // Second sentence, let's insert it as a paragraph after the previously inserted one.
  let secondSentence = context.document.body.insertParagraph(
    "This is the first text with a custom style.",
    "End"
  );
  secondSentence.font.set({
    bold: false,
    italic: true,
    name: "Berlin Sans FB",
    color: "blue",
    size: 30
  });

  await context.sync();
});

Inserts a paragraph at the specified location.

[ API set: WordApi 1.1 ]

insertParagraph(paragraphText: string, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace"): Word.Paragraph;

Parameters

Returns

Inserts a table with the specified number of rows and columns.

[ API set: WordApi 1.3 ]

insertTable(rowCount: number, columnCount: number, insertLocation: Word.InsertLocation, values?: string[][]): Word.Table;

Parameters

Returns

Inserts a table with the specified number of rows and columns.

[ API set: WordApi 1.3 ]

insertTable(rowCount: number, columnCount: number, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace", values?: string[][]): Word.Table;

Parameters

Returns

Inserts text into the paragraph at the specified location.

[ API set: WordApi 1.1 ]

insertText(text: string, insertLocation: Word.InsertLocation): Word.Range;

Parameters

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the paragraphs collection.
    var paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for the top 2 paragraphs.
    // We never perform an empty load. We always must request a property.
    context.load(paragraphs, {select: 'style', top: 2} );

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {

        // Queue a command to get the first paragraph.
        var paragraph = paragraphs.items[0];

        // Queue a command to insert text into the end of the paragraph.
        paragraph.insertText('New text inserted into the paragraph.', Word.InsertLocation.end);

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            console.log('Inserted text at the end of the first paragraph.');
        });
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

await Word.run(async (context) => {
  // Replace the last paragraph.
  let range = context.document.body.paragraphs.getLast().insertText("Just replaced the last paragraph!", "Replace");
  range.font.highlightColor = "black";
  range.font.color = "white";

  await context.sync();
});

Inserts text into the paragraph at the specified location.

[ API set: WordApi 1.1 ]

insertText(text: string, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace"): Word.Range;

Parameters

Returns

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

load(option?: Word.Interfaces.ParagraphLoadOptions): Word.Paragraph;

Parameters

Returns

Remarks

In addition to this signature, this method has the following signatures:

load(option?: string | string[]): Word.Paragraph - Where option is a comma-delimited string or an array of strings that specify the properties to load.

load(option?: { select?: string; expand?: string; }): Word.Paragraph - Where option.select is a comma-delimited string that specifies the properties to load, and options.expand is a comma-delimited string that specifies the navigation properties to load.

load(option?: { select?: string; expand?: string; top?: number; skip?: number }): Word.Paragraph - Only available on collection types. It is similar to the preceding signature. Option.top specifies the maximum number of collection items that can be included in the result. Option.skip specifies the number of items that are to be skipped and not included in the result. If option.top is specified, the result set will start after skipping the specified number of items.

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNames?: string | string[]): Word.Paragraph;

Parameters

Returns

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths?: { select?: string; expand?: string; }): Word.Paragraph;

Parameters

Returns

Performs a search with the specified SearchOptions on the scope of the paragraph object. The search results are a collection of range objects.

[ API set: WordApi 1.1 ]

search(searchText: string, searchOptions?: Word.SearchOptions | {
            ignorePunct?: boolean;
            ignoreSpace?: boolean;
            matchCase?: boolean;
            matchPrefix?: boolean;
            matchSuffix?: boolean;
            matchWholeWord?: boolean;
            matchWildcards?: boolean;
        }): Word.RangeCollection;

Parameters

Returns

Selects and navigates the Word UI to the paragraph.

[ API set: WordApi 1.1 ]

select(selectionMode?: Word.SelectionMode): void;

Parameters

Returns

Examples

// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the paragraphs collection.
    var paragraphs = context.document.body.paragraphs;

    // Queue a command to load the style property for all of the paragraphs.
    context.load(paragraphs, 'style');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {

        // Queue a command to get the last paragraph a create a
        // proxy paragraph object.
        var paragraph = paragraphs.items[paragraphs.items.length - 1];

        // Queue a command to select the paragraph. The Word UI will
        // move to the selected paragraph.
        paragraph.select();

        // Synchronize the document state by executing the queued commands,
        // and return a promise to indicate task completion.
        return context.sync().then(function () {
            console.log('Selected the last paragraph.');
        });
    });
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

await Word.run(async (context) => {
  // If select is called with no parameters, it selects the object.
  context.document.body.paragraphs.getLast().select();

  await context.sync();
});

await Word.run(async (context) => {
  // Select can be at the start or end of a range; this by definition moves the insertion point without selecting the range.
  context.document.body.paragraphs.getLast().select("End");

  await context.sync();
});

Selects and navigates the Word UI to the paragraph.

[ API set: WordApi 1.1 ]

select(selectionModeString?: "Select" | "Start" | "End"): void;

Parameters

Returns

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties: Interfaces.ParagraphUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parameters

Returns

Remarks

This method has the following additional signature:

set(properties: Word.Paragraph): void

Examples

await Word.run(async (context) => {
  const paragraph = context.document.body.paragraphs.getFirst();
  paragraph.set({
    leftIndent: 30,
    font: {
      bold: true,
      color: "red"
    }
  });

  await context.sync();
});

await Word.run(async (context) => {
  const firstParagraph = context.document.body.paragraphs.getFirst();
  const secondParagraph = firstParagraph.getNext();
  firstParagraph.load("text, font/color, font/bold, leftIndent");

  await context.sync();

  secondParagraph.set(firstParagraph);

  await context.sync();
});

Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Word.Paragraph): void;

Parameters

Returns

Splits the paragraph into child ranges by using delimiters.

[ API set: WordApi 1.3 ]

split(delimiters: string[], trimDelimiters?: boolean, trimSpacing?: boolean): Word.RangeCollection;

Parameters

Returns

Examples

await Word.run(async (context) => {
  let paragraph = context.document.body.paragraphs.getFirst();
  let words = paragraph.split([" "], true /* trimDelimiters*/, true /* trimSpaces */);
  words.load("text");

  await context.sync();

  for (let i = 0; i < words.items.length; i++) {
    if (i >= 1) {
      words.items[i - 1].font.highlightColor = "#FFFFFF";
    }
    words.items[i].font.highlightColor = "#FFFF00";

    await context.sync();
    await pause(200);
  }
});

Starts a new list with this paragraph. Fails if the paragraph is already a list item.

[ API set: WordApi 1.3 ]

startNewList(): Word.List;

Returns

Examples

// This example starts a new list stating with the second paragraph.
await Word.run(async (context) => {
  let paragraphs = context.document.body.paragraphs;
  paragraphs.load("$none"); // No properties needed.

  await context.sync();

  var list = paragraphs.items[1].startNewList(); // Indicates new list to be started in the second paragraph.
  list.load("$none"); // No properties needed.

  await context.sync();

  // To add new items to the list use start/end on the insert location parameter.
  list.insertParagraph("New list item on top of the list", "Start");
  let paragraph = list.insertParagraph("New list item at the end of the list (4th level)", "End");
  paragraph.listItem.level = 4; // Sets up list level for the lsit item.
  // To add paragraphs outside the list use before/after:
  list.insertParagraph("New paragraph goes after (not part of the list)", "After");

  await context.sync();
});

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Word.Paragraph object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.ParagraphData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Word.Interfaces.ParagraphData;

Returns

Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you are using this object across ".sync" calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you needed to have added the object to the tracked object collection when the object was first created.

track(): Word.Paragraph;

Returns

Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You will need to call "context.sync()" before the memory release takes effect.

untrack(): Word.Paragraph;

Returns