Share via

Word API returns outlineLevel = 10 for first heading paragraph inside Content Control regardless of heading style

Koduri Santosh 0 Reputation points
2026-05-18T03:58:04.4133333+00:00

We are using the Word JavaScript API for section/content control hierarchy processing. While creating a section inside a content control, the first line/paragraph inside the content control is not being identified correctly by the Word API.

If the first line is assigned any heading style (Heading 1, Heading 2, etc.), the API still returns outlineLevel = 10 for that paragraph instead of the expected outline level.

Because of this, our hierarchy logic treats the paragraph as normal/body content and the section creation flow fails at the root level.

We also verified this using the native Word Navigation Pane. The first line inside the content control is not recognized as a heading there, while subsequent heading paragraphs inside the same content control are recognized correctly.

Expected behavior: If a paragraph has a heading style applied, the API should return the correct outline level.

Actual behavior: For the first line/paragraph inside the content control, the API returns outlineLevel = 10 regardless of the heading style applied. Subsequent heading paragraphs inside the same content control are identified correctly.

Microsoft 365 and Office | Development | Office JavaScript API
0 comments

2 answers

Sort by: Most helpful
Most helpful Newest Oldest
  1. Dora-T 13,745 Reputation points Microsoft External Staff Moderator
    2026-05-18T05:25:40.58+00:00

    Hi Koduri Santosh

    Based on my testing directly in Microsoft Word, it appears that Word may be internally treating the first paragraph inside the content control as part of the content control boundary rather than as a normal outline-recognized heading paragraph. This would explain why the first heading returns outlineLevel = 10 and is also not recognized in the Navigation Pane, while subsequent headings work correctly. 

    As a possible workaround, could you try inserting an empty paragraph before the first heading inside the content control and then check whether the heading is recognized correctly afterward? 

    For example: 

    Content Control 

    Empty paragraph 

    Heading 1 

    Body content 

    As a moderator, I can provide technical guidance and best-practice recommendations based on public documentation, reported issues, and community discussions. However, my testing environment is limited. If the behavior continues after testing the workaround above, I would recommend opening a new thread on GitHub, where engineers and community contributors familiar with the Office JavaScript API may be able to provide more targeted insights. 

    Reference: Participating in a discussion - GitHub Docs.   

    Apologies for redirecting you to the development community, and thank you for your understanding. 

    Note: Please follow the steps in our documentation to enable e-mail notifications if you want to receive the related email notification for this thread.

    Was this answer helpful?

  2. AI answer

    2026-05-18T03:58:35.5766667+00:00

    This behavior is consistent with how Word exposes outline levels and headings in the APIs and UI.

    Key points from the available information:

    1. Outline level vs. heading style
      • In the COM object model, both Paragraph.OutlineLevel and _ParagraphFormat.OutlineLevel “return or set the outline level for the specified paragraphs.”
      • If a paragraph has a heading style applied (Heading 1–Heading 9), “the outline level is the same as the heading style and cannot be changed.”
      • Outline levels are only visible in Outline view or the Navigation/Document Map pane.
    2. JavaScript API representation
      • In the Word JavaScript API, Word.Paragraph.toJSON() returns a ParagraphData object whose outlineLevel property “specifies the outline level for the paragraph.”
      • This is the same conceptual value as the COM OutlineLevel property.
    3. Content controls and headings
      • Content controls are a separate feature; the context shows that new content control types and behaviors were added over time (for example, repeating section content controls in Word 2013), but there is no documented special case where the first paragraph inside a content control is treated differently for outline level.
    4. Known content-control-related API issues
      • There is a documented issue where ContentControl.load() could fail with RichApi.Error: NotImplemented because it attempted to load unreleased properties. This was fixed, and the guidance is to explicitly load only the needed properties.
      • However, this issue is about load failures, not incorrect outlineLevel values.

    Given the documentation, the expected behavior is exactly what is described in the question: when a heading style is applied, the paragraph’s outline level should match that heading (1–9) and be reflected both in the Navigation Pane and in ParagraphData.outlineLevel. There is no documented exception for the first paragraph inside a content control.

    Because of that, the described behavior (first paragraph inside a content control always reporting outlineLevel = 10 and not appearing in the Navigation Pane, while subsequent heading paragraphs work correctly) aligns with an implementation bug rather than a documented or supported behavior.

    Actionable guidance based on the documented APIs:

    1. Use outlineLevel as the canonical indicator of heading hierarchy.
    2. Verify that the heading style is actually applied to the paragraph (not just direct formatting) and that the style is one of Heading 1–Heading 9.
    3. If the paragraph is inside a content control and the Navigation Pane also fails to show it as a heading, treat this as a product issue rather than a coding error.
    4. As a workaround in hierarchy logic, consider:
      • Ignoring the first paragraph’s outlineLevel when it is 10 but the style name is a heading style, or
      • Starting hierarchy detection from the second paragraph inside the content control.
    5. Ensure Word is updated to the latest build, as other content-control-related issues (such as the ContentControl.load() bug) have been fixed via service updates.

    If the issue persists on the latest build, it should be reported as a bug through the Office Developer support channels, including a minimal repro using Word.Paragraph and ParagraphData.outlineLevel inside a content control.

    References:

    AI-generated content may be incorrect. Read our transparency notes for more information.

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.