MS Word Office.js API to add new content control along with text "before" target content control in WEB version

[ajithhegdeoracle]

Body

Hi !
I am developing MS Word Add-in using typescript where-
Word document will have "target content control" and need to add new content control "before" the target.
I followed the typescript code like below (not the exact code, tried multiple trials)-

const controls = context.document.contentControls;
controls.load("items/tag,id");
await context.sync();
const control = controls.items.find((c: any) => {
        const tag = (c.tag || "").trim();
        return tag && tag.startsWith(targetTag);
      });
let paragraph: Word.Paragraph;
if (position === "before"){
const beforeRange = (control as any).getRange(Word.RangeLocation.before);
paragraph = beforeRange.insertParagraph("<some text>", Word.InsertLocation.after);
const cc = paragraph.insertContentControl();
}

Issue I am seeing is-
newly added content control along with text is added at the beginning of the target content control.
When I hover on those, it shows the boundary like this-

|---------------------------------------------------|
| |-----------------------------------|  
| | new content control                 
| |-----------------------------------|   
| target content control                    
|---------------------------------------------------|

Expectation is to have two separate content controls.
It works in Desktop but not in Web version.
Is this case feasible in Word web version? If Yes, please suggest sample typescript code.
Thanks!

Guidelines

• I have read and understood this category's guidelines before making this post.

[flexycode]

Hey! I've run into this exact behavior before. The inconsistency between Desktop and Web when handling ranges at the boundaries of Content Controls is super annoying.

The issue stems from how you are defining the insertion point. When you grab getRange(Word.RangeLocation.before) and then insert text Word.InsertLocation.after that range, the Web engine interprets that "sticky" boundary as being inside the nearest container (your target control).

To fix this, you should avoid manipulating the Range and instead insert the paragraph directly on the Content Control object. This tells the engine to create a structural sibling node, rather than guessing where the text belongs.

Try this approach:

await Word.run(async (context) => {
    const targetTag = "YourTargetTag";
    
    // Grab your controls
    const controls = context.document.contentControls;
    controls.load("items/tag, items/id");
    await context.sync();

    const targetControl = controls.items.find((c) => {
        const tag = (c.tag || "").trim();
        return tag && tag.startsWith(targetTag);
    });

    if (targetControl) {
        // THE FIX: Insert directly relative to the Control, not a Range.
        // This forces the new paragraph to be a sibling, not a child.
        const newParagraph = targetControl.insertParagraph(
            "<some text>", 
            Word.InsertLocation.before
        );

        // Crucial step for Web: Sync here to establish the paragraph in the DOM
        // before you try to act on it.
        newParagraph.load("range");
        await context.sync();

        // Now add the control to the new paragraph
        const newCC = newParagraph.getRange().insertContentControl();
        newCC.appearance = Word.ContentControlAppearance.boundingBox; // Optional visual aid
        
        await context.sync();
    }
});

The key difference here is targetControl.insertParagraph(..., Word.InsertLocation.before). Also, don't skip the intermediate context.sync()—the Web version is much stricter about objects needing to be fully instantiated before you can wrap them in a new CC.

[IndAlok]

Okay, so the problem you're running into with Word Online is a common one. It's all about how the web version handles those Range Boundary things. When you use getRange(Word.RangeLocation.before), Word Online sometimes thinks that spot is still inside the Content Control. So, whatever you stick there ends up getting pulled into the existing control instead of chilling outside it.

To dodge this issue and keep things separate on both the desktop and web versions, skip making a range yourself. Just have the ContentControl object do the insertion work directly.

Here's the easiest way to do it with TypeScript:

// Find the control you're aiming for (like you're already doing)
const targetControl = controls.items.find((c: any) => {
    return (c.tag || ).trim().startsWith(targetTag);
});

if (targetControl && position === before) {
    // 1. Shove the paragraph in directly BEFORE the control.
    // This makes sure the new paragraph is outside the target's area.
    const newParagraph = targetControl.insertParagraph(<some text="">, Word.InsertLocation.before);

    // 2. Wrap the</some> new paragraph in its own content control.
    const newCC = newParagraph.insertContentControl();
    
    // If you want, set some details for the new control
    newCC.tag = new-control-tag;
    
    await context.sync();
}

• Direct Aim: When you tell targetControl.insertParagraph(..., before), you're telling Office.js to put the new thing right up against the control's outside edge.
• No Overlap: When you grab a range before the control and sneak something after that range, Word Online tends to put you right back on the target control's starting line.
• Paragraphs Stay Put: Because you're dropping in a whole paragraph, Word has to make a split, block-level separation, which helps stop that nested boundary look you're seeing.

Give this a shot – it's way more reliable across the board than messing with those RangeLocation points yourself.