BlockLevelContainer

BlockLevelContainer:

{
  blocklevels(): BlockLevel[];
  addParagraph(index?: number): Paragraph;
  addTable(index?: number): Table;
  removeElement(index: number): BlockLevel | undefined;
  setParagraphList(target: ParagraphRange, options: ParagraphListOptions): void;
  applyParagraphListFrom(sourceIndex: number, target: ParagraphRange, options?: ApplyParagraphListFromOptions): void;
  replaceText: ReplaceTextSignature;
}

Container for block-level elements (paragraphs and tables).

Remarks

BlockLevelContainer is implemented by Body.content, TableCell, and HeaderFooter, providing methods to manage block-level content within these containers.

Examples

Adding paragraphs and tables:

const content = draft.body().content();
const paragraph = content.addParagraph(); // Append paragraph at end
const table = content.addTable(0);    // Insert table at start

Accessing and removing elements:

const elements = content.blocklevels();
const removed = content.removeElement(0);

Properties

replaceText

replaceText: ReplaceTextSignature

Searches and replaces text within this container. See ReplaceTextSignature.

Methods

blocklevels()

blocklevels(): BlockLevel[]

Returns all block-level elements in this container.

Returns

BlockLevel[]

addParagraph()

addParagraph(index?): Paragraph

Adds a new paragraph. If index is provided, inserts at that position; otherwise appends to the end.

Parameters

index?

number

Returns

Paragraph

addTable()

addTable(index?): Table

Adds a new table. If index is provided, inserts at that position; otherwise appends to the end.

Parameters

index?

number

Returns

Table

removeElement()

removeElement(index): BlockLevel | undefined

Removes the element at the specified index. Returns the removed element, or undefined if index is out of bounds.

Parameters

index

number

Returns

BlockLevel | undefined

setParagraphList()

setParagraphList(target, options): void

Applies or clears list formatting for a contiguous range of existing paragraph block-level elements.

Parameters

Remarks

target.index and target.count refer to the current blocklevels() order. Every block in the range must be a paragraph; the method throws when the range is out of bounds or includes a table. Omit level to use top-level list items.

Use { kind: 'none' } to remove list formatting while keeping paragraph text.

Example

const content = section.content();
const start = content.blocklevels().length;

content.addParagraph().asTextView().setText('Draft announcement');
content.addParagraph().asTextView().setText('Prepare demo');
content.addParagraph().asTextView().setText('Send follow-up');

content.setParagraphList({ index: start, count: 3 }, { kind: 'bullet' });

// Produces:
// • Draft announcement
// • Prepare demo
// • Send follow-up

applyParagraphListFrom()

applyParagraphListFrom(sourceIndex, target, options?): void

Applies list state from one paragraph to a contiguous range of existing paragraph block-level elements.

Parameters

sourceIndex

number

target

ParagraphRange

options?

ApplyParagraphListFromOptions

Returns

void

Remarks

This preserves imported or custom list formatting by reusing the source paragraph’s existing list format. By default the target paragraphs continue the source paragraph’s list instance. Pass { list: 'startNew' } to start a separate list instance with the same format.

The source paragraph must be a list item with a resolvable list format in the document list format table, and the requested level must exist in that list format. The target range must be in bounds and contain only paragraphs.

Throws

RangeError when sourceIndex or target is out of bounds, when options.level is outside the supported range, or when the source list format does not define the requested level.

Throws

TypeError when sourceIndex points to a table, when the source paragraph is not a list item, or when target includes a table.

Example

const content = section.content();
const sourceIndex = 2;
const start = content.blocklevels().length;

content.addParagraph().asTextView().setText('Follow up');
content.addParagraph().asTextView().setText('Send recap');

content.applyParagraphListFrom(sourceIndex, { index: start, count: 2 });

// If sourceIndex points to "3. Existing item", this appends:
// 4. Follow up
// 5. Send recap