Static HTML inside @ref element?

[NightProgramming]

There is some mentioning of the requirement of @ref elements to be empty:

"Only use an element reference to mutate the contents of an empty element that doesn't interact with Blazor."

"The recommended technique is to have the component's code (.razor file) produce an empty element. As far as Blazor's diffing system is concerned, the element is always empty, so the renderer does not recurse into the element and instead leaves its contents alone."

"The <div> with @ref="mapElement" is left empty as far as Blazor is concerned. The mapbox-gl.js script can safely populate the element and modify its contents."

"It is not safe for external JS code to modify elements that Blazor does not regard as empty."

The warning section says though:

"it's dangerous to mutate the contents of the unordered list (ul) because Blazor interacts with the DOM to populate this element's list items (<li>) from the Todos object"

Also some dangerous sample code is given:

<ul @ref="MyList">
    @foreach (var item in Todos)
    {
        <li>@item.Text</li>
    }
</ul>

The other parts of the page say that @ref elements always should be empty, but the dangerous sample code and the text above it indicate, at least to me, that the danger actually comes from having Blazor manipulating something inside the @ref element (in this case because of the @foreach directive).

Now the obvious question arises: What if there is only static HTML inside the @ref element, e.g.:

<div @ref="MyDiv">
    <p>Some text.</p>
</ul>

And then have some JS that does something with <p> or adds siblings to <p> or whatever.

According to the parts of the page that say that @ref elements always should be empty, it's wrong to do that. But according to what the warning section indicates, it shouldn't be a problem because Blazor shouldn't manipulate anything inside this @ref div element.

Which one holds true? The current docs make it look like there is some uncertainty regarding what can actually cause problems. If @ref elements simply always have to empty then the docs would seem clearer to me without the warning section. Or keep the warning section but then please also explain why having only static HTML inside the @ref also isn't possible. Or if it is possible then please edit the other parts that say that it has to be empty.

---

Document details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

• ID: 2b7ea38a-649b-303d-bebf-c701e216ba25
• Version Independent ID: 9e197a8b-2616-8363-0a15-38cac802e82e
• Content: Call JavaScript functions from .NET methods in ASP.NET Core Blazor
• Content Source: aspnetcore/blazor/javascript-interoperability/call-javascript-from-dotnet.md
• Product: aspnet-core
• Technology: aspnetcore-blazor
• GitHub Login: @guardrex
• Microsoft Alias: riande

[guardrex]

Hello @NightProgramming ... Sorry for the delay. I'm OOF for a few days and will be back to take a look at the end of the week.

[guardrex]

Hello @NightProgramming ... I'm back.

For ...

the dangerous sample code and the text above it indicate, at least to me, that the danger actually comes from having Blazor manipulating something inside the @ref element (in this case because of the @foreach directive).

The danger would be if YOU used JS interop with the element reference to modify the content of that list. It's covered by the next remark (under the example code) ...

If JS interop mutates the contents of element MyList and Blazor attempts to apply diffs to the element, the diffs won't match the DOM.

However, we probably can trigger events and read content, where content isn't modified in the process. We probably need to add a remark on that.

@SteveSandersonMS ... Is it correct that all of these remarks about JS interop with element references focus on modifying content, not triggering events and reading HTML content?

@SteveSandersonMS ... WRT the "empty" element remarks: I assume that the product unit literally means "empty" if you intend to modify the content, but I need to ask to confirm it. The guidance is ...

Only use an element reference to mutate the contents of an empty element that doesn't interact with Blazor.

Does it literally mean empty (as I assume it means from a plain reading), or can the element have static HTML that Blazor doesn't interact with and the developer uses JS interop with the element reference (or via a JS lib) to modify the contents? As @NightProgramming points out, we probably need to flesh out the answer to this question one way or the other.

[SteveSandersonMS]

Is it correct that all of these remarks about JS interop with element references focus on modifying content, not triggering events and reading HTML content?

Yes, it's perfectly fine to read information from any DOM element, whether or not Blazor will render and change it later.

Does it literally mean empty (as I assume it means from a plain reading), or can the element have static HTML that Blazor doesn't interact with and the developer uses JS interop with the element reference (or via a JS lib) to modify the contents?

You would have to differentiate "what works today in practice" from "what scenarios we officially support".

The only custom-JS-mutates-the-DOM scenario we're explicitly saying is definitely safe is if the element is literally empty as far as Blazor is concerned.

In practice, if the element is nonempty but the content never changes, then nothing bad would actually happen if you mutated it given the current renderer implementation, since after the first render the diffing system will normally not need to update that content again. However we reserve the right to change how the renderer works at any time and maybe in the future it might for some reason care about the statically-rendered content remaining unchanged. The one scenario we are promising to keep working forever is the element is empty as far as Blazor is concerned.

As far as docs are concerned I'm not sure I'd try to cover this explicitly since the docs become unwieldy if they contain all these caveats. They are already correct to describe the supported scenario.

[guardrex]

Thanks @SteveSandersonMS ... I'll merely add a quick, passing remark that triggering events and reading DOM content is fine where it speaks to not mutating content. I'll leave the rest of the text alone.