Add JavaScript to Blazor
Before you can interact with a JavaScript library, you need to add it to Blazor first. In this tutorial, you will discover:
- JavaScript module and standard JavaScript.
- Global standard JavaScript.
- Load JavaScript module on demand.
You can download the example code used in this topic on GitHub.
JavaScript module and standard JavaScript
There are 2 types of JavaScript: module and standard. You will need to determine what is your JavaScript library type before using it. We assume that you understand what is JavaScript module and standard JavaScript, we will give you a quick catch-up to distinguish between the two. A JavaScript module is a file of classes/functions declared with export keyword. A standard JavaScript is a file of classes/functions declared without the export keyword. For example:
A JavaScript module:
export function exampleFunction()
{
alert("Hello Blazor School")
}
A standard JavaScript:
function exampleFunction()
{
alert("Hello Blazor School")
}
A JavaScript module can contain one or more export declaration. The following code is also a JavaScript module:
export function exampleFunction1()
{
alert("Hello Blazor School")
}
export function exampleFunction2()
{
alert("Hello Blazor School")
}
Global standard JavaScript
This technique will let you use a standard JavaScript function everywhere in your website. To implement this technique, you need to load your standard JavaScript with <script> tag. There are 2 places that you can put your <script> tag: inside <head> tag and inside <body> tag.
Advantages
- Easy to implement.
- Can apply to some specific libraries.
Disadvantages
- Pollute the naming pool.
- Make first render slower.
Import in <head>
Import in <head> tag will block the render thread until every script in the <head> are fetched. It will make your website slow down on the first render. Most of the time, you don't need to put scripts in the <head> tag.
Import in <body>
Import in <body> tag is a good way. By doing this, you will not block the render thread and allow the <script> tags to be fetched asynchronously.
Implementation
- Put your standard JavaScript file in wwwroot.
- In your Pages/_Host.cshtml, add the
<script>tag to import the standard JavaScript.
For example: assuming you have the wwwroot/js/global.js. Your _Host.cshtml will look like:
...
<!DOCTYPE html>
<html lang="en">
<head>
...
</head>
<body>
...
<script src="_framework/blazor.server.js"></script>
<script src="~/js/global.js"></script>
</body>
</html>
You cannot make a JavaScript module as global.
You must put your script under wwwroot folder.
Load JavaScript module on demand
This technique will let you load a JavaScript module only when you need it. Each JavaScript module has it own scope. This means you can have 2 functions with the same name in different modules. There are 2 places to put your JavaScript module: wwwroot and collocate with a component.
Advantages
- Don't pollute the naming pool.
- Make first render faster.
- Can apply to some specific libraries.
Disadvantage
- Have to write more code.
Module in wwwroot
You will need to put your module file under the wwwroot folder. There is no side effect for this approach.
Collocate with a component
You will need to name your module as <ComponentName>.razor.js. When done correctly, you will see your JavaScript module and Razor component nested like this (File nesting must be turned on):
Implementation
- In your component, inject the
IJSRuntimeand implement theIAsyncDisposableinterface in the directive section.
@inject IJSRuntime JS @implements IAsyncDisposable
- Declare a
Lazy<IJSObjectReference>or each of your module in the code section. For example:
@code {
private Lazy<IJSObjectReference> ExampleModule = new();
}
- In the code section, initialize the
Lazy<IJSObjectReference>and dispose it after use. For example:
@code {
...
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender)
{
ExampleModule = new(await JS.InvokeAsync<IJSObjectReference>("import", "./js/exampleModule.js"));
}
}
public async ValueTask DisposeAsync()
{
if(ExampleModule.IsValueCreated)
{
await ExampleModule.Value.DisposeAsync();
}
}
}
You can initialize it in another life cycle method hook. However, OnAfterRenderAsync method is preferred because you don't need the JavaScript when render your component in server.
For collocated JavaScript module, you need to change the path to JavaScript module. For example, you have the following folder tree:
Then you need to change the path to JavaScript module as follows:
CollocateJsModule = new(await JS.InvokeAsync<IJSObjectReference>("import", "./Pages/LoadOnDemand/CollocateJS.razor.js"));
