MutationObserver
React to DOM changes from C#: ObserveMutations is an extension method on any ElementReference that reports added and removed nodes, attribute changes and text edits as strongly typed records - no polling, no JavaScript.
Capture the element with the ref directive and call ObserveMutations with the IJSRuntime and a handler. With no options it defaults to watching added and removed nodes across the whole subtree - the most common case. Start observing, then add and remove items to see childList records arrive.
IJSRuntime js
<div @ref="container">...</div>
{
private ElementReference container;
private ButilSubscription? subscription;
private async Task Start()
{
// defaults to ChildList = true, Subtree = true
subscription = await container.ObserveMutations(js, records =>
{
foreach (var record in records)
{
Console.WriteLine($"{record.Type}: +{record.AddedCount} / -{record.RemovedCount}");
}
});
}
}Set Attributes to true to receive a record for every attribute change on the target. AttributeOldValue includes the previous value in each record, and AttributeFilter narrows the watch to specific attribute names so unrelated changes stay silent.
await container.ObserveMutations(js, records =>
{
foreach (var record in records)
{
Console.WriteLine($"{record.AttributeName}: {record.OldValue} -> changed");
}
}, new MutationObserverOptions
{
Attributes = true,
AttributeOldValue = true,
AttributeFilter = ["data-state"],
});CharacterData watches edits to text nodes; pair it with Subtree so text anywhere inside the container is covered, and CharacterDataOldValue to receive the previous text. Incrementing the counter below makes Blazor update a text node inside the observed container.
await container.ObserveMutations(js, records =>
{
foreach (var record in records)
{
Console.WriteLine($"text changed, was: {record.OldValue}");
}
}, new MutationObserverOptions
{
CharacterData = true,
CharacterDataOldValue = true,
Subtree = true,
});DOM nodes cannot cross the interop boundary, so each MutationRecord is a flattened summary: the mutation type, the target's tag name and id, the attribute name and old value where applicable, and how many nodes were added or removed.
await container.ObserveMutations(js, records =>
{
foreach (var record in records)
{
var type = record.Type; // "childList" | "attributes" | "characterData"
var tag = record.TargetTagName; // e.g. "DIV"
var id = record.TargetId; // element id, when present
var attr = record.AttributeName; // attributes mutations only
var old = record.OldValue; // when *OldValue options are enabled
var added = record.AddedCount; // childList mutations only
var removed = record.RemovedCount;
}
});ObserveMutations returns a ButilSubscription; disposing it disconnects the observer and releases the interop reference. Dispose every observer you start - at the latest in your component's DisposeAsync, as this page does.
IAsyncDisposable
private ButilSubscription? subscription;
public async ValueTask DisposeAsync()
{
if (subscription is not null)
{
await subscription.DisposeAsync();
}
}API reference
Task<ButilSubscription> ObserveMutations(IJSRuntime js, Action<MutationRecord[]> handler, MutationObserverOptions? options = null)bool ChildList { get; set; }bool Attributes { get; set; }bool CharacterData { get; set; }bool Subtree { get; set; }bool AttributeOldValue { get; set; }bool CharacterDataOldValue { get; set; }string[]? AttributeFilter { get; set; }string Type { get; set; }string TargetTagName { get; set; }string? TargetId { get; set; }string? AttributeName { get; set; }string? AttributeNamespace { get; set; }string? OldValue { get; set; }int AddedCount { get; set; }int RemovedCount { get; set; }Guid Id { get; }ValueTask DisposeAsync()