Use JS Interop
.NET (Microsoft)OfficialPublished by .NET (Microsoft)
- Skill
- Tool integration
- Software development
- MIT
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides a structured approach to integrating JavaScript with Blazor components. It emphasizes the use of collocated .razor.js modules, strongly typed C# interop wrappers, and efficient batching of calls to minimize performance overhead. It covers critical lifecycle management, including proper disposal of JS references, handling JS-to-.NET callbacks, and ensuring server-side safety in Blazor Server environments.
What it does
- Defines patterns for collocated JavaScript modules using export functions.
- Provides a template for creating strongly typed C# interop wrapper classes.
- Outlines lifecycle rules for executing JS interop in OnAfterRenderAsync.
- Demonstrates how to batch multiple interop calls to reduce boundary crossings.
- Explains the safe use of DotNetObjectReference for JS-to-.NET communication.
- Details proper disposal patterns using IAsyncDisposable to prevent memory leaks.
When to use it
- When you need to call JavaScript functions from a Blazor component.
- When you need to expose .NET methods to JavaScript.
- When you are managing the lifecycle of JS objects within a Blazor component.
- When you need to pass DOM elements to JavaScript safely using ElementReference.
- When you need to optimize performance by reducing the number of JS interop round-trips.
Advantages
- Reduces runtime errors by using typed wrappers instead of magic strings.
- Improves performance by batching interop calls.
- Ensures memory safety through proper IAsyncDisposable implementation.
- Maintains clean project structure with collocated JS files.
- Prevents common pitfalls like calling JS during server prerendering.
Usage examples
- “How do I call a JavaScript function from my Blazor component?”
- The skill guides you to create a collocated .razor.js file, export the function, and invoke it from the component's OnAfterRenderAsync method using a typed interop wrapper.
- “How can I send data from JavaScript back to my Blazor component?”
- The skill shows how to pass a DotNetObjectReference to JS, define a public [JSInvokable] method in C#, and invoke it from JS using a try/catch block.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/dotnet/use-js-interop/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip use-js-interop.zip -d .agents/skills
Documentation by .NET (Microsoft)
JS Interop in Blazor
1. Collocated JS Modules
Always use collocated .razor.js files with export — never global window.* functions or <script> tags.
// ChartPanel.razor.js — placed next to ChartPanel.razor
export function initialize(canvas, dotNetRef) { /* ... */ }
export function updateData(points) { /* ... */ }
export function dispose() { /* ... */ }Import paths: same project = "./Components/ChartPanel.razor.js", RCL = "./_content/{AssemblyName}/...".
2. Lifecycle Timing
All JS interop must happen in OnAfterRenderAsync or event handlers — never in OnInitialized, OnParametersSet, or constructors. JS is not available during server prerendering.
Use a typed interop wrapper (see Section 4) — never call InvokeAsync/InvokeVoidAsync with raw string literals:
private ChartInterop? _chart;
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender)
{
_chart = new ChartInterop(JS);
await _chart.InitializeAsync(_canvasRef);
}
}Parameter changes: set a flag in OnParametersSet, apply in OnAfterRenderAsync:
private bool _dataChanged;
protected override void OnParametersSet() => _dataChanged = true;
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender) { /* init */ }
else if (_dataChanged && _chart is not null)
{
_dataChanged = false;
await _chart.UpdateDataAsync(DataPoints);
}
}3. Batch Related Operations
Each JS interop call crosses the .NET-to-JS boundary (and in Blazor Server, the SignalR circuit). Batching applies in both directions — .NET→JS and JS→.NET.
.NET → JS: merge consecutive calls
If the C# side makes two or more JS calls in a row, combine them into one JS function:
// ❌ Two round-trips — theme and locale are always applied together
await _module.InvokeVoidAsync("applyTheme", theme);
await _module.InvokeVoidAsync("applyLocale", locale);
// ❌ Result of one call feeds into another — both can stay in JS
var token = await _module.InvokeAsync<string>("createAccessToken");
await _module.InvokeVoidAsync("storeToken", token);// ✅ One call applies both — no data dependency, no reason for two trips
export function applyPreferences(theme, locale) {
document.documentElement.dataset.theme = theme;
document.documentElement.lang = locale;
}
// ✅ Chain stays in JS — the token never needs to cross the boundary
export function createAndStoreToken() {
const token = crypto.randomUUID();
sessionStorage.setItem('access-token', token);
return token;
}JS → .NET: batch callbacks
When JS needs to send multiple pieces of data back to .NET, send them in a single invokeMethodAsync call rather than making separate callbacks:
// ❌ Two .NET round-trips from JS
await dotNetRef.invokeMethodAsync(ON_VOLUME_CHANGED, volume);
await dotNetRef.invokeMethodAsync(ON_PLAYBACK_CHANGED, isPlaying);
// ✅ One callback with all data
await dotNetRef.invokeMethodAsync(ON_PLAYER_STATE_CHANGED, { volume, isPlaying });Rule: if two interop calls always happen together from either side, merge them into one function.
4. Typed Interop Wrapper
Encapsulate interop for a feature in a plain class that owns the module lifecycle:
public sealed class ChartInterop : IAsyncDisposable
{
internal const string ModulePath = "./Components/ChartPanel.razor.js";
internal const string InitMethod = "initialize";
internal const string UpdateMethod = "updateData";
internal const string DisposeMethod = "dispose";
private readonly IJSRuntime _js;
private IJSObjectReference? _module;
public ChartInterop(IJSRuntime js) => _js = js;
private async ValueTask<IJSObjectReference> GetModuleAsync()
=> _module ??= await _js.InvokeAsync<IJSObjectReference>("import", ModulePath);
public async ValueTask InitializeAsync(ElementReference canvas)
{
var module = await GetModuleAsync();
await module.InvokeVoidAsync(InitMethod, canvas);
}
public async ValueTask UpdateDataAsync(IReadOnlyList<DataPoint> points)
{
var module = await GetModuleAsync();
await module.InvokeVoidAsync(UpdateMethod, points);
}
public async ValueTask DisposeAsync()
{
try
{
if (_module is not null)
{
await _module.InvokeVoidAsync(DisposeMethod);
await _module.DisposeAsync();
}
}
catch (JSDisconnectedException) { }
}
}The component creates and uses the wrapper with no magic strings:
@inject IJSRuntime JS
@implements IAsyncDisposable
<canvas @ref="_canvasRef" width="600" height="400"></canvas>
@code {
private ElementReference _canvasRef;
private ChartInterop? _chart;
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender)
{
_chart = new ChartInterop(JS);
await _chart.InitializeAsync(_canvasRef);
}
}
async ValueTask IAsyncDisposable.DisposeAsync()
{
if (_chart is not null)
await _chart.DisposeAsync();
}
}Prefer a concrete class over interface + implementation for interop wrappers. For unit testing, substitute IJSRuntime directly (it is already an interface).
5. DotNetObjectReference for JS-to-.NET Callbacks
_dotNetRef = DotNetObjectReference.Create(this);
await _module.InvokeVoidAsync("initialize", _dotNetRef);On the JS side, wrap the dotNetRef in a class. Use async/await with try/catch (not .catch()) to guard against circuit loss. Define .NET method name constants at the top:
const ON_CLIPBOARD_CHANGED = 'OnClipboardChanged';
class ClipboardMonitor {
#dotNetRef;
#abortController;
constructor(dotNetRef) {
this.#dotNetRef = dotNetRef;
this.#abortController = new AbortController();
}
start() {
document.addEventListener('copy', async () => {
try {
const text = await navigator.clipboard.readText();
await this.#dotNetRef.invokeMethodAsync(ON_CLIPBOARD_CHANGED, text);
} catch { /* circuit disconnected or clipboard denied */ }
}, { signal: this.#abortController.signal });
}
dispose() {
this.#abortController.abort();
}
}
let monitor;
export function initialize(dotNetRef) {
monitor = new ClipboardMonitor(dotNetRef);
monitor.start();
}
export function dispose() {
monitor?.dispose();
}Rules:
[JSInvokable]methods must bepublic— private/internal silently fails at runtimeWrap
StateHasChangedinInvokeAsyncinside[JSInvokable]callbacks:[JSInvokable] public async Task OnClipboardChanged(string text) { await InvokeAsync(() => { _lastClipboard = text; StateHasChanged(); }); }Always
try/catcharoundinvokeMethodAsyncin JS — circuit loss throwsUse
constfor .NET method name strings in JS — prevents typo bugs that silently failDispose
DotNetObjectReferenceinDisposeAsync
6. Disposal and Server Safety
Always implement IAsyncDisposable. Call JS cleanup first, then dispose references. Catch JSDisconnectedException for Blazor Server circuit loss:
public async ValueTask DisposeAsync()
{
try
{
if (_module is not null)
{
await _module.InvokeVoidAsync("dispose");
await _module.DisposeAsync();
}
}
catch (JSDisconnectedException) { }
_dotNetRef?.Dispose();
}Never use sync IDisposable for JS interop cleanup — InvokeVoidAsync returns ValueTask and must be awaited.
7. ElementReference
Pass DOM elements via @ref, not string IDs:
<canvas @ref="_canvasRef" width="600" height="400"></canvas>await _chart.InitializeAsync(_canvasRef);Checklist
[ ] JS is in collocated
.razor.jswithexport— nowindow.*globals[ ] All interop in
OnAfterRenderAsyncor event handlers — never during prerender[ ]
IAsyncDisposablecatchesJSDisconnectedException[ ]
DotNetObjectReferencedisposed inDisposeAsync; JS side hastry/catcharoundinvokeMethodAsync[ ]
[JSInvokable]methods arepublicand useawait InvokeAsync(StateHasChanged)[ ]
InvokeVoidAsyncused when no return value is needed[ ]
ElementReferenceinstead of string IDs[ ] Related operations batched into single interop calls (both .NET→JS and JS→.NET)
Common Mistakes Checklist
| Mistake | Fix |
|---|---|
| Using JS for something achievable with CSS | Use CSS custom properties, data- attributes, pseudo-classes |
| Many fine-grained interop calls | Batch into coarse functions — both .NET→JS and JS→.NET |
| Component imports JS module directly | Encapsulate in a strongly typed interop class |
| Magic strings for method names / module paths | Define internal const fields in the interop class |
| Interface + implementation for interop wrapper | Use a plain class; mock IJSRuntime for tests instead |
JS calls in OnInitializedAsync | Move to OnAfterRenderAsync(firstRender) |
InvokeAsync<object> for void calls | Use InvokeVoidAsync |
IDisposable with fire-and-forget JS | Use IAsyncDisposable with await |
Global window.* JS functions | Use collocated .razor.js with export |
| String element IDs passed to JS | Use ElementReference with @ref |
[JSInvokable] on private method | Must be public — silently fails otherwise |
DotNetObjectReference not disposed | Dispose in DisposeAsync — causes memory leak |
StateHasChanged() without InvokeAsync | Wrap in await InvokeAsync(() => { StateHasChanged(); }) |
JS invokeMethodAsync without error handling | Wrap in try/catch — circuit loss throws |
Bare dotNetRef in JS event handlers | Wrap in a class with #dotNetRef private field |
Magic strings in JS invokeMethodAsync calls | Use const at module top — typos silently fail at runtime |
JS calls in OnParametersSetAsync | Track changes, apply in OnAfterRenderAsync with guard |
| No null check before calling module | Check module is not null before use |
Files
- ATTRIBUTION.mdAdded by AutoGineer841 B
- LICENSELicence file added by AutoGineer1.1 KiB
- SKILL.md10.7 KiB
SKILL.md
JS Interop in Blazor
1. Collocated JS Modules
Always use collocated .razor.js files with export — never global window.* functions or <script> tags.
// ChartPanel.razor.js — placed next to ChartPanel.razor
export function initialize(canvas, dotNetRef) { /* ... */ }
export function updateData(points) { /* ... */ }
export function dispose() { /* ... */ }Import paths: same project = "./Components/ChartPanel.razor.js", RCL = "./_content/{AssemblyName}/...".
2. Lifecycle Timing
All JS interop must happen in OnAfterRenderAsync or event handlers — never in OnInitialized, OnParametersSet, or constructors. JS is not available during server prerendering.
Use a typed interop wrapper (see Section 4) — never call InvokeAsync/InvokeVoidAsync with raw string literals:
private ChartInterop? _chart;
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender)
{
_chart = new ChartInterop(JS);
await _chart.InitializeAsync(_canvasRef);
}
}Parameter changes: set a flag in OnParametersSet, apply in OnAfterRenderAsync:
private bool _dataChanged;
protected override void OnParametersSet() => _dataChanged = true;
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender) { /* init */ }
else if (_dataChanged && _chart is not null)
{
_dataChanged = false;
await _chart.UpdateDataAsync(DataPoints);
}
}3. Batch Related Operations
Each JS interop call crosses the .NET-to-JS boundary (and in Blazor Server, the SignalR circuit). Batching applies in both directions — .NET→JS and JS→.NET.
.NET → JS: merge consecutive calls
If the C# side makes two or more JS calls in a row, combine them into one JS function:
// ❌ Two round-trips — theme and locale are always applied together
await _module.InvokeVoidAsync("applyTheme", theme);
await _module.InvokeVoidAsync("applyLocale", locale);
// ❌ Result of one call feeds into another — both can stay in JS
var token = await _module.InvokeAsync<string>("createAccessToken");
await _module.InvokeVoidAsync("storeToken", token);// ✅ One call applies both — no data dependency, no reason for two trips
export function applyPreferences(theme, locale) {
document.documentElement.dataset.theme = theme;
document.documentElement.lang = locale;
}
// ✅ Chain stays in JS — the token never needs to cross the boundary
export function createAndStoreToken() {
const token = crypto.randomUUID();
sessionStorage.setItem('access-token', token);
return token;
}JS → .NET: batch callbacks
When JS needs to send multiple pieces of data back to .NET, send them in a single invokeMethodAsync call rather than making separate callbacks:
// ❌ Two .NET round-trips from JS
await dotNetRef.invokeMethodAsync(ON_VOLUME_CHANGED, volume);
await dotNetRef.invokeMethodAsync(ON_PLAYBACK_CHANGED, isPlaying);
// ✅ One callback with all data
await dotNetRef.invokeMethodAsync(ON_PLAYER_STATE_CHANGED, { volume, isPlaying });Rule: if two interop calls always happen together from either side, merge them into one function.
4. Typed Interop Wrapper
Encapsulate interop for a feature in a plain class that owns the module lifecycle:
public sealed class ChartInterop : IAsyncDisposable
{
internal const string ModulePath = "./Components/ChartPanel.razor.js";
internal const string InitMethod = "initialize";
internal const string UpdateMethod = "updateData";
internal const string DisposeMethod = "dispose";
private readonly IJSRuntime _js;
private IJSObjectReference? _module;
public ChartInterop(IJSRuntime js) => _js = js;
private async ValueTask<IJSObjectReference> GetModuleAsync()
=> _module ??= await _js.InvokeAsync<IJSObjectReference>("import", ModulePath);
public async ValueTask InitializeAsync(ElementReference canvas)
{
var module = await GetModuleAsync();
await module.InvokeVoidAsync(InitMethod, canvas);
}
public async ValueTask UpdateDataAsync(IReadOnlyList<DataPoint> points)
{
var module = await GetModuleAsync();
await module.InvokeVoidAsync(UpdateMethod, points);
}
public async ValueTask DisposeAsync()
{
try
{
if (_module is not null)
{
await _module.InvokeVoidAsync(DisposeMethod);
await _module.DisposeAsync();
}
}
catch (JSDisconnectedException) { }
}
}The component creates and uses the wrapper with no magic strings:
@inject IJSRuntime JS
@implements IAsyncDisposable
<canvas @ref="_canvasRef" width="600" height="400"></canvas>
@code {
private ElementReference _canvasRef;
private ChartInterop? _chart;
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender)
{
_chart = new ChartInterop(JS);
await _chart.InitializeAsync(_canvasRef);
}
}
async ValueTask IAsyncDisposable.DisposeAsync()
{
if (_chart is not null)
await _chart.DisposeAsync();
}
}Prefer a concrete class over interface + implementation for interop wrappers. For unit testing, substitute IJSRuntime directly (it is already an interface).
5. DotNetObjectReference for JS-to-.NET Callbacks
_dotNetRef = DotNetObjectReference.Create(this);
await _module.InvokeVoidAsync("initialize", _dotNetRef);On the JS side, wrap the dotNetRef in a class. Use async/await with try/catch (not .catch()) to guard against circuit loss. Define .NET method name constants at the top:
const ON_CLIPBOARD_CHANGED = 'OnClipboardChanged';
class ClipboardMonitor {
#dotNetRef;
#abortController;
constructor(dotNetRef) {
this.#dotNetRef = dotNetRef;
this.#abortController = new AbortController();
}
start() {
document.addEventListener('copy', async () => {
try {
const text = await navigator.clipboard.readText();
await this.#dotNetRef.invokeMethodAsync(ON_CLIPBOARD_CHANGED, text);
} catch { /* circuit disconnected or clipboard denied */ }
}, { signal: this.#abortController.signal });
}
dispose() {
this.#abortController.abort();
}
}
let monitor;
export function initialize(dotNetRef) {
monitor = new ClipboardMonitor(dotNetRef);
monitor.start();
}
export function dispose() {
monitor?.dispose();
}Rules:
[JSInvokable]methods must bepublic— private/internal silently fails at runtimeWrap
StateHasChangedinInvokeAsyncinside[JSInvokable]callbacks:[JSInvokable] public async Task OnClipboardChanged(string text) { await InvokeAsync(() => { _lastClipboard = text; StateHasChanged(); }); }Always
try/catcharoundinvokeMethodAsyncin JS — circuit loss throwsUse
constfor .NET method name strings in JS — prevents typo bugs that silently failDispose
DotNetObjectReferenceinDisposeAsync
6. Disposal and Server Safety
Always implement IAsyncDisposable. Call JS cleanup first, then dispose references. Catch JSDisconnectedException for Blazor Server circuit loss:
public async ValueTask DisposeAsync()
{
try
{
if (_module is not null)
{
await _module.InvokeVoidAsync("dispose");
await _module.DisposeAsync();
}
}
catch (JSDisconnectedException) { }
_dotNetRef?.Dispose();
}Never use sync IDisposable for JS interop cleanup — InvokeVoidAsync returns ValueTask and must be awaited.
7. ElementReference
Pass DOM elements via @ref, not string IDs:
<canvas @ref="_canvasRef" width="600" height="400"></canvas>await _chart.InitializeAsync(_canvasRef);Checklist
[ ] JS is in collocated
.razor.jswithexport— nowindow.*globals[ ] All interop in
OnAfterRenderAsyncor event handlers — never during prerender[ ]
IAsyncDisposablecatchesJSDisconnectedException[ ]
DotNetObjectReferencedisposed inDisposeAsync; JS side hastry/catcharoundinvokeMethodAsync[ ]
[JSInvokable]methods arepublicand useawait InvokeAsync(StateHasChanged)[ ]
InvokeVoidAsyncused when no return value is needed[ ]
ElementReferenceinstead of string IDs[ ] Related operations batched into single interop calls (both .NET→JS and JS→.NET)
Common Mistakes Checklist
| Mistake | Fix |
|---|---|
| Using JS for something achievable with CSS | Use CSS custom properties, data- attributes, pseudo-classes |
| Many fine-grained interop calls | Batch into coarse functions — both .NET→JS and JS→.NET |
| Component imports JS module directly | Encapsulate in a strongly typed interop class |
| Magic strings for method names / module paths | Define internal const fields in the interop class |
| Interface + implementation for interop wrapper | Use a plain class; mock IJSRuntime for tests instead |
JS calls in OnInitializedAsync | Move to OnAfterRenderAsync(firstRender) |
InvokeAsync<object> for void calls | Use InvokeVoidAsync |
IDisposable with fire-and-forget JS | Use IAsyncDisposable with await |
Global window.* JS functions | Use collocated .razor.js with export |
| String element IDs passed to JS | Use ElementReference with @ref |
[JSInvokable] on private method | Must be public — silently fails otherwise |
DotNetObjectReference not disposed | Dispose in DisposeAsync — causes memory leak |
StateHasChanged() without InvokeAsync | Wrap in await InvokeAsync(() => { StateHasChanged(); }) |
JS invokeMethodAsync without error handling | Wrap in try/catch — circuit loss throws |
Bare dotNetRef in JS event handlers | Wrap in a class with #dotNetRef private field |
Magic strings in JS invokeMethodAsync calls | Use const at module top — typos silently fail at runtime |
JS calls in OnParametersSetAsync | Track changes, apply in OnAfterRenderAsync with guard |
| No null check before calling module | Check module is not null before use |
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- .NET (Microsoft)
- Publisher
- .NET (Microsoft) (Official)
- Source
- dotnet/skills · plugins/dotnet-blazor/skills/use-js-interop · commit 96c3d68
- Licence
- MIT License (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by .NET (Microsoft).
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download use-js-interop.zip