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://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
LICENSE
The MIT License (MIT) Copyright (c) .NET Foundation and Contributors All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
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) or .NET (Microsoft).
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download use-js-interop.zip