Paragraph

Paragraph:

{
  type: "paragraph";
  asTextView(): TextView;
  setParagraphProperties(properties: Partial<ParagraphProperties>, options?: ParagraphPropertiesOptions): void;
  list(): ParagraphListState | null;
  replaceText: ReplaceTextSignature;
  hasSectionBreak(): boolean;
  addSectionBreak(): void;
  removeSectionBreak(): void;
  findSection(): Section | undefined;
}

Represents a paragraph block-level element within a document.

Remarks

Paragraph is one of the primary block-level elements in a document (along with Table). It contains content like text, images, line breaks, and other elements.

Paragraphs are obtained from:

• BlockLevelContainer.blocklevels - Get all block-level elements
• BlockLevelContainer.addParagraph - Create a new paragraph

To work with paragraph content, use asTextView to get a TextView interface that provides methods for reading and manipulating the text and inline elements.

Examples

Iterate through all paragraphs in the body:

for (const bl of document.body().content().blocklevels()) {
  if (bl.type === 'paragraph') {
    const textView = bl.asTextView();
    const text = textView.getPlainText();
    console.log('Paragraph text:', text);
  }
}

Add and populate a new paragraph at the end of the body:

const newPara = document.body().content().addParagraph();

// Set text content
const textView = newPara.asTextView();
textView.setText('This is a new paragraph.');

// Apply formatting
textView.setFormatting({ bold: true, fontSize: 14 });

Properties

type

type: "paragraph"

Type discriminator for block-level elements.

Remarks

Always has the value 'paragraph'. Use this property to narrow the block-level element type and access paragraph-specific methods.

---

replaceText

replaceText: ReplaceTextSignature

Replaces all occurrences of a pattern with new content.

Remarks

Convenience method equivalent to calling TextView.replaceText on the result of asTextView. Searches for all matches of the pattern within this paragraph and replaces them with the specified content.

See ReplaceTextSignature for detailed parameter and usage information.

Examples

if (blockLevel.type === 'paragraph') {
  // Replace all "TODO" with "DONE"
  const count = blockLevel.replaceText(/TODO/g, 'DONE');
  console.log(`Replaced ${count} occurrences`);
}

if (blockLevel.type === 'paragraph') {
  // Replace with formatting
  blockLevel.replaceText(/ERROR/gi, {
    text: 'ERROR',
    formatting: { color: '#ff0000', bold: true }
  });
}

Methods

asTextView()

asTextView(): TextView

Gets a TextView interface for reading and manipulating the paragraph’s content.

Returns

TextView

A TextView that provides access to the paragraph’s inline elements

Remarks

Returns a TextView interface that exposes methods for working with the paragraph’s text and inline elements. Use this to:

• Read text content (TextView.getPlainText)
• Search for text (TextView.searchText)
• Modify text (TextView.setText)
• Apply formatting (TextView.setFormatting)
• Access inline elements (TextView.inlines)

Example

if (blockLevel.type === 'paragraph') {
  const textView = blockLevel.asTextView();
  const text = textView.getPlainText();
  console.log('Paragraph content:', text);
}

---

setParagraphProperties()

NEW

setParagraphProperties(properties, options?): void

Applies paragraph-level properties to this paragraph.

Parameters

properties

Partial<ParagraphProperties>

Partial paragraph properties to apply

options?

ParagraphPropertiesOptions

Options controlling how paragraph properties are applied

Returns

void

Remarks

Only properties included in properties are modified. This method changes paragraph properties such as alignment; use TextView.setFormatting for inline text styling. Use options.clear to clear direct paragraph properties before applying the requested properties.

Examples

paragraph.setParagraphProperties({ alignment: 'justify' });

Apply a built-in paragraph style and clear direct paragraph-level overrides:

paragraph.setParagraphProperties({ styleId: 'Heading 1' }, { clear: true });

---

list()

list(): ParagraphListState | null

Returns this paragraph’s list state, or null when this paragraph is not a list item.

Returns

ParagraphListState | null

Remarks

The list API reports simple SDK-created bullet and numbered lists as paragraph list kinds. Imported or custom list formats that cannot be safely classified by the API are reported with unsupported: true.

Example

if (blockLevel.type === 'paragraph') {
  const list = blockLevel.list();
  if (list && 'kind' in list) {
    console.log(`List item at level ${list.level}: ${list.kind}`);
  }
}

---

hasSectionBreak()

hasSectionBreak(): boolean

Returns true if this paragraph carries a section break — i.e. it is the last block of a non-trailing section. Body-level paragraphs are the only ones for which this is meaningful; nested paragraphs (inside headers, footers, or table cells) always return false.

Returns

boolean

---

addSectionBreak()

addSectionBreak(): void

Adds a section break to this paragraph, closing the section it currently belongs to and starting a new page. The new section inherits the formatting of the section it closes.

Returns

void

Remarks

Silent no-op if the paragraph already carries a section break, or if it is not a body-level paragraph.

---

removeSectionBreak()

removeSectionBreak(): void

Removes the section break from this paragraph, merging this section with the next one. The merged section keeps the formatting of the section that was being closed; the formatting of the section that followed is dropped.

Returns

void

Remarks

Silent no-op if the paragraph does not carry a section break, or if it is not a body-level paragraph.

---

findSection()

findSection(): Section | undefined

Returns the Section containing this paragraph, or undefined if this paragraph is not a body-level block (e.g. it is nested inside a header, footer, or table cell, or has been removed from the body).

Returns

Section | undefined

Example

const block = body.content().blocklevels()[3];
if (block.type === 'paragraph') {
  const section = block.findSection();
  section?.pageSetup().setPageMargins({ top: 36, bottom: 36, left: 72, right: 72 });
}