ASP.NET Core Blazor JavaScript interoperability (JS interop)

A Blazor app can invoke JavaScript (JS) functions from .NET methods and .NET methods from JS functions. These scenarios are called JavaScript interoperability (JS interop).

Further JS interop guidance is provided in the following articles:

• Call JavaScript functions from .NET methods in ASP.NET Core Blazor
• Call .NET methods from JavaScript functions in ASP.NET Core Blazor

Note

JavaScript [JSImport]/[JSExport] interop API is available for client-side components in ASP.NET Core in .NET 7 or later.

For more information, see JavaScript JSImport/JSExport interop with ASP.NET Core Blazor.

JavaScript interop abstractions and features package

The @microsoft/dotnet-js-interop package (npmjs.com) (Microsoft.JSInterop NuGet package) provides abstractions and features for interop between .NET and JavaScript (JS) code. Reference source is available in the dotnet/aspnetcore GitHub repository (/src/JSInterop folder). For more information, see the GitHub repository's README.md file.

Note

Documentation links to .NET reference source usually load the repository's default branch, which represents the current development for the next release of .NET. To select a tag for a specific release, use the Switch branches or tags dropdown list. For more information, see How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205).

Additional resources for writing JS interop scripts in TypeScript:

• TypeScript
• Tutorial: Create an ASP.NET Core app with TypeScript in Visual Studio
• Manage npm packages in Visual Studio

Interaction with the DOM

Only mutate the DOM with JavaScript (JS) when the object doesn't interact with Blazor. Blazor maintains representations of the DOM and interacts directly with DOM objects. If an element rendered by Blazor is modified externally using JS directly or via JS Interop, the DOM may no longer match Blazor's internal representation, which can result in undefined behavior. Undefined behavior may merely interfere with the presentation of elements or their functions but may also introduce security risks to the app or server.

This guidance not only applies to your own JS interop code but also to any JS libraries that the app uses, including anything provided by a third-party framework, such as Bootstrap JS and jQuery.

In a few documentation examples, JS interop is used to mutate an element purely for demonstration purposes as part of an example. In those cases, a warning appears in the text.

For more information, see Call JavaScript functions from .NET methods in ASP.NET Core Blazor.

Asynchronous JavaScript calls

JS interop calls are asynchronous by default, regardless of whether the called code is synchronous or asynchronous. Calls are asynchronous by default to ensure that components are compatible across server-side and client-side rendering models. When adopting server-side rendering, JS interop calls must be asynchronous because they're sent over a network connection. For apps that exclusively adopt client-side rendering, synchronous JS interop calls are supported.

For more information, see the following articles:

• Call JavaScript functions from .NET methods in ASP.NET Core Blazor
• Call .NET methods from JavaScript functions in ASP.NET Core Blazor

Object serialization

Blazor uses System.Text.Json for serialization with the following requirements and default behaviors:

• Types must have a default constructor, get/set accessors must be public, and fields are never serialized.
• Global default serialization isn't customizable to avoid breaking existing component libraries, impacts on performance and security, and reductions in reliability.
• Serializing .NET member names results in lowercase JSON key names.
• JSON is deserialized as JsonElement C# instances, which permit mixed casing. Internal casting for assignment to C# model properties works as expected in spite of any case differences between JSON key names and C# property names.
• Complex framework types, such as KeyValuePair, might be trimmed away by the IL Trimmer on publish and not present for JS interop. We recommend creating custom types for types that the IL Trimmer trims away by default.

JsonConverter API is available for custom serialization. Properties can be annotated with a [JsonConverter] attribute to override default serialization for an existing data type.

For more information, see the following resources in the .NET documentation:

• JSON serialization and deserialization (marshalling and unmarshalling) in .NET
• How to customize property names and values with System.Text.Json
• How to write custom converters for JSON serialization (marshalling) in .NET

Blazor supports optimized byte array JS interop that avoids encoding/decoding byte arrays into Base64. The app can apply custom serialization and pass the resulting bytes. For more information, see Call JavaScript functions from .NET methods in ASP.NET Core Blazor.

DOM cleanup tasks during component disposal

Don't execute JS interop code for DOM cleanup tasks during component disposal. Instead, use the MutationObserver pattern in JavaScript (JS) on the client for the following reasons:

• The component may have been removed from the DOM by the time your cleanup code executes in Dispose{Async}.
• During server-side rendering, the Blazor renderer may have been disposed by the framework by the time your cleanup code executes in Dispose{Async}.

The MutationObserver pattern allows you to run a function when an element is removed from the DOM.

In the following example, the DOMCleanup component:

• Contains a <div> with an id of cleanupDiv. The <div> element is removed from the DOM along with the rest of the component's DOM markup when the component is removed from the DOM.
• Loads the DOMCleanup JS class from the DOMCleanup.razor.js file and calls its createObserver function to set up the MutationObserver callback. These tasks are accomplished in the OnAfterRenderAsync lifecycle method.

DOMCleanup.razor:

@page "/dom-cleanup"
@implements IAsyncDisposable
@inject IJSRuntime JS

<h1>DOM Cleanup Example</h1>

<div id="cleanupDiv"></div>

@code {
    private IJSObjectReference? module;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            module = await JS.InvokeAsync<IJSObjectReference>(
                "import", "./Components/Pages/DOMCleanup.razor.js");

            await module.InvokeVoidAsync("DOMCleanup.createObserver");
        }
    }

    async ValueTask IAsyncDisposable.DisposeAsync()
    {
        if (module is not null)
        {
            await module.DisposeAsync();
        }
    }
}

In the following example, the MutationObserver callback is executed each time a DOM change occurs. Execute your cleanup code when the if statement confirms that the target element (cleanupDiv) was removed (if (targetRemoved) { ... }). It's important to disconnect and delete the MutationObserver to avoid a memory leak after your cleanup code executes.

DOMCleanup.razor.js placed side-by-side with the preceding DOMCleanup component:

export class DOMCleanup {
  static observer;

  static createObserver() {
    const target = document.querySelector('#cleanupDiv');

    this.observer = new MutationObserver(function (mutations) {
      const targetRemoved = mutations.some(function (mutation) {
        const nodes = Array.from(mutation.removedNodes);
        return nodes.indexOf(target) !== -1;
      });

      if (targetRemoved) {
        // Cleanup resources here
        // ...

        // Disconnect and delete MutationObserver
        this.observer && this.observer.disconnect();
        delete this.observer;
      }
    });

    this.observer.observe(target.parentNode, { childList: true });
  }
}

window.DOMCleanup = DOMCleanup;

JavaScript interop calls without a circuit

This section only applies to server-side apps.

JavaScript (JS) interop calls can't be issued after a SignalR circuit is disconnected. Without a circuit during component disposal or at any other time that a circuit doesn't exist, the following method calls fail and log a message that the circuit is disconnected as a JSDisconnectedException:

• JS interop method calls
  • IJSRuntime.InvokeAsync
  • JSRuntimeExtensions.InvokeAsync
  • JSRuntimeExtensions.InvokeVoidAsync)
• Dispose/DisposeAsync calls on any IJSObjectReference.

In order to avoid logging JSDisconnectedException or to log custom information, catch the exception in a try-catch statement.

For the following component disposal example:

• The component implements IAsyncDisposable.
• objInstance is an IJSObjectReference.
• JSDisconnectedException is caught and not logged.
• Optionally, you can log custom information in the catch statement at whatever log level you prefer. The following example doesn't log custom information because it assumes the developer doesn't care about when or where circuits are disconnected during component disposal.

async ValueTask IAsyncDisposable.DisposeAsync()
{
    try
    {
        if (objInstance is not null)
        {
            await objInstance.DisposeAsync();
        }
    }
    catch (JSDisconnectedException)
    {
    }
}

If you must clean up your own JS objects or execute other JS code on the client after a circuit is lost, use the MutationObserver pattern in JS on the client. The MutationObserver pattern allows you to run a function when an element is removed from the DOM.

For more information, see the following articles:

• Handle errors in ASP.NET Core Blazor apps: The JavaScript interop section discusses error handling in JS interop scenarios.
• ASP.NET Core Razor component lifecycle: The Component disposal with IDisposable and IAsyncDisposable section describes how to implement disposal patterns in Razor components.

Cached JavaScript files

JavaScript (JS) files and other static assets aren't generally cached on clients during development in the Development environment. During development, static asset requests include the Cache-Control header with a value of no-cache or max-age with a value of zero (0).

During production in the Production environment, JS files are usually cached by clients.

To disable client-side caching in browsers, developers usually adopt one of the following approaches:

• Disable caching when the browser's developer tools console is open. Guidance can be found in the developer tools documentation of each browser maintainer:
  • Chrome DevTools
  • Firefox Developer Tools
  • Microsoft Edge Developer Tools overview
• Perform a manual browser refresh of any webpage of the Blazor app to reload JS files from the server. ASP.NET Core's HTTP Caching Middleware always honors a valid no-cache Cache-Control header sent by a client.

For more information, see:

• ASP.NET Core Blazor environments
• Response caching in ASP.NET Core

Size limits on JavaScript interop calls

This section only applies to interactive components in server-side apps. For client-side components, the framework doesn't impose a limit on the size of JavaScript (JS) interop inputs and outputs.

For interactive components in server-side apps, JS interop calls passing data from the client to the server are limited in size by the maximum incoming SignalR message size permitted for hub methods, which is enforced by HubOptions.MaximumReceiveMessageSize (default: 32 KB). JS to .NET SignalR messages larger than MaximumReceiveMessageSize throw an error. The framework doesn't impose a limit on the size of a SignalR message from the hub to a client. For more information on the size limit, error messages, and guidance on dealing with message size limits, see ASP.NET Core Blazor SignalR guidance.

Determine where the app is running

If it's relevant for the app to know where code is running for JS interop calls, use OperatingSystem.IsBrowser to determine if the component is executing in the context of browser on WebAssembly.