Reference scripts in Blazor Application

25 Apr 202321 minutes to read

This section provides information about the script isolation process and how to reference scripts from CDN, Static Web Assets and Custom resource generator (CRG) for Syncfusion Blazor Components.

NOTE

The javascript interop files needs to be added to support the features that can’t be implemented in native blazor.

CDN Reference

You can refer the Syncfusion Blazor scripts through the CDN resources.

NOTE

From 2022 Vol1 (20.1) version, JavaScript isolation is marked as obsolete and disabled by default and it was completely removed in the 2023 Vol1 (21.1) version to refer scripts externally. This means that the feature is no longer available in the latest versions. Refer Disable JavaScript isolation topic to disable for earlier versions to refer scripts externally.

For Blazor WASM App, reference scripts in ~/wwwroot/index.html file.
For Blazor Server App, reference scripts in ~/Pages/_Layout.cshtml file for .NET 6 project and in ~/Pages/_Host.cshtml file for .NET Core 3.X, .NET 5 and .NET 7 project.

Syncfusion Blazor components are available in CDN for each version. Make sure that the version in the URLs matches the version of the Syncfusion Blazor Package you are using.

Component	CDN Script Reference
All components except PDF Viewer & Document Editor	CSHTML `https://cdn.syncfusion.com/blazor/21.1.35/syncfusion-blazor.min.js`
PDF Viewer	CSHTML `https://cdn.syncfusion.com/blazor/21.1.35/syncfusion-blazor-pdfviewer.min.js`
Document Editor	CSHTML `https://cdn.syncfusion.com/blazor/21.1.35/syncfusion-blazor-documenteditor.min.js`

<head>
    ....
    <script src="https://cdn.syncfusion.com/blazor/21.1.35/syncfusion-blazor.min.js" type="text/javascript"></script>
</head>

If you are using PDFViewer or DocumentEditor, ensure to add additional script references as follows,

<head>
    ....
    <script src="https://cdn.syncfusion.com/blazor/21.1.35/syncfusion-blazor-pdfviewer.min.js" type="text/javascript"></script>
    <script src="https://cdn.syncfusion.com/blazor/21.1.35/syncfusion-blazor-documenteditor.min.js" type="text/javascript"></script>
</head>

In addition to above, Syncfusion Blazor components provides latest scripts in CDN without versioning. You can use this in development environment if you want to always use the latest version of scripts. It is not recommended to use this in production environment.

WARNING

The un-versioned CDN links which always maintains latest version scripts are deprecated from 2022 Vol1 - 20.1 version. These links are available with 19.4 version scripts to avoid breaking in sites and apps that uses un-versioned links.

Component	CDN Script Reference
All components except PDF Viewer & Document Editor	https://cdn.syncfusion.com/blazor/syncfusion-blazor.min.js
PDF Viewer	https://cdn.syncfusion.com/blazor/syncfusion-blazor-pdfviewer.min.js
Document Editor	https://cdn.syncfusion.com/blazor/syncfusion-blazor-documenteditor.min.js

Static web assets

You can refer the Syncfusion Blazor scripts through the NuGet package’s static web assets.

NOTE

From 2022 Vol1 (20.1) version, JavaScript isolation is marked as obsolete and disabled by default and it was completely removed in the 2023 Vol1 (21.1) version to refer scripts externally. This means that the feature is no longer available in the latest versions. Refer Disable JavaScript isolation topic to disable for earlier versions to refer scripts externally.

Enable static web assets usage

To use static web assets, ensure UseStaticFiles method is called as follows,

For .NET 6 and .NET 7 app, open the ~/Program.cs file and call UseStaticFiles method.
For .NET 5 and .NET 3.X app, open the ~/Startup.cs file and call UseStaticFiles method.

NOTE

For Blazor WASM App, call UseStaticFiles method in Server project of the above mentioned file.

Refer script from static web assets

If you are using Syncfusion Blazor individual NuGet package, the combined scripts available in Syncfusion.Blazor.Core package. To refer script from static web assets, use the code below.
```
  <head>
      ...
      <script  src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"  type="text/javascript"></script>
  </head>
```

If you’re using the PDF viewer or Document Editor component, use the code below to refer to script from static web assets.

  <head>
      ...
     <script  src="_content/Syncfusion.Blazor.PdfViewer/scripts/syncfusion-blazor-pdfviewer.min.js"  type="text/javascript"></script>
     <script  src="_content/Syncfusion.Blazor.WordProcessor/scripts/syncfusion-blazor-documenteditor.min.js"  type="text/javascript"></script>
  </head>

If you are using Syncfusion.Blazor NuGet package, use the code below to refer to script from static web assets.

It is not recommended to use Syncfusion.Blazor NuGet for production environment. Use individual NuGet packages for production.
```
  <head>
      ...
      <script  src="_content/Syncfusion.Blazor/scripts/syncfusion-blazor.min.js"  type="text/javascript"></script>
  </head>
```
NOTE

The PDF Viewer and Document Editor component scripts are available in static web assets from 19.3.* version. If you are using PDF Viewer or Document Editor component with 19.2.* version, it automatically switch to the JavaScript isolation in the application end.

JavaScript isolation

Syncfusion Blazor components supports JavaScript isolation where the needed scripts are loaded by the component itself when its rendered. So, you don’t have to reference scripts externally in application.

NOTE

The Built-in JavaScript isolation feature has been marked as deprecated in 2022 Vol1 release and it has been completely removed in the 2023 Vol1 (21.1) release, since loading scripts externally provides better performance over JavaScript isolation approach. This means that the JavaScript isolation feature is no longer available in the latest versions. If you are still using it, we recommend loading scripts externally via CDN, Static Web Assets and CRG.

If you are using 20.* and before release versions, you can enable JavaScript isolation by following steps,

Blazor Server App

For .NET 6 and .NET 7 app, open the ~/Program.cs file and register the Syncfusion Blazor Service by setting IgnoreScriptIsolation as false.
For .NET 5 and .NET 3.X app, open the ~/Startup.cs file and register the Syncfusion Blazor Service by setting IgnoreScriptIsolation as false.

.NET 6 & .NET 7 (~/Program.cs)
.NET 5 and .NET 3.X (~/Startup.cs)
using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.Web;
using Syncfusion.Blazor;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
builder.Services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = false; });

var app = builder.Build();
....
using Syncfusion.Blazor;

namespace BlazorApplication
{
    public class Startup
    {
        ...
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddServerSideBlazor();
            services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = false; });
        }
        ...
    }
}

Blazor WASM App

For Blazor WebAssembly App, set IgnoreScriptIsolation property as false using AddSyncfusionBlazor service method in ~/Program.cs file.

.NET 6 & .NET 7 (~/Program.cs)
.NET 5 & .NET 3.X (~/Program.cs)
using Microsoft.AspNetCore.Components.Web;
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Syncfusion.Blazor;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

builder.Services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = false; });
await builder.Build().RunAsync();
....
using Syncfusion.Blazor;

namespace WebApplication1
{
    public class Program
    {
        public static async Task Main(string[] args)
        {
            ....
            builder.Services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = false; });
            await builder.Build().RunAsync();
        }
    }
}

Disable JavaScript isolation

NOTE

From 2022 Vol1 (20.1) version, JavaScript isolation is marked as obsolete and disabled by default and it has been completely removed in the 2023 Vol1 (21.1) release, since loading scripts externally provides better performance over JavaScript isolation approach. This means that the JavaScript isolation feature is no longer available in the latest (21.*) versions. You don’t have to make below additional changes.

The Syncfusion Blazor components supports to refer scripts externally at the application-end by disabling default JavaScript isolation approach for better initial loading performance which explained in the previous section. If you are using 20.* and before release versions, you can disable JS isolation by setting IgnoreScriptIsolation as true while adding Syncfusion blazor service using AddSyncfusionBlazor().

Blazor Server App

For .NET 6 and .NET 7 app, open the ~/Program.cs file and register the Syncfusion Blazor Service by setting IgnoreScriptIsolation.
For .NET 5 and .NET 3.X app, open the ~/Startup.cs file and register the Syncfusion Blazor Service by setting IgnoreScriptIsolation.

.NET 6 & .NET 7 (~/Program.cs)
.NET 5 and .NET 3.X (~/Startup.cs)
using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.Web;
using Syncfusion.Blazor;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
builder.Services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = true; });

var app = builder.Build();
....
using Syncfusion.Blazor;

namespace BlazorApplication
{
    public class Startup
    {
        ...
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddServerSideBlazor();
            services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = true; });
        }
        ...
    }
}

Blazor WASM App

For Blazor WebAssembly App, set IgnoreScriptIsolation property as true using AddSyncfusionBlazor service method in ~/Program.cs file.

.NET 6 & .NET 7 (~/Program.cs)
.NET 5 & .NET 3.X (~/Program.cs)
using Microsoft.AspNetCore.Components.Web;
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Syncfusion.Blazor;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });

builder.Services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = true; });
await builder.Build().RunAsync();
....
using Syncfusion.Blazor;

namespace WebApplication1
{
    public class Program
    {
        public static async Task Main(string[] args)
        {
            ....
            builder.Services.AddSyncfusionBlazor(options => { options.IgnoreScriptIsolation = true; });
            await builder.Build().RunAsync();
        }
    }
}

NOTE

If you set IgnoreScriptIsolation property as true, You need to reference scripts externally via Static Web Assets or CDN or and CRG.

Individual control script reference

Syncfusion Blazor components provides component-wise scripts which can be referenced externally in application. If you are using minimal components, then you can import the selected components scripts via CDN or Static web assets directly without using CRG instead of referencing single script with all components.

You can add a component script reference in one of the following ways based on usage,

Usage	Script reference
Refer from Static web assets when using Syncfusion.Blazor NuGet	CSHTML `<head> ... <!--<script src="_content/Syncfusion.Blazor/scripts/<Component script name>" type="text/javascript"></script>--> <script src="_content/Syncfusion.Blazor/scripts/sf-textbox.min.js" type="text/javascript"></script> </head>`
Refer from Static web assets when using individual NuGet packages	CSHTML `<head> ... <!--<script src="_content/<Package name>/scripts/<Component script name>" type="text/javascript"></script>--> <script src="_content/Syncfusion.Blazor.Inputs/scripts/sf-textbox.min.js" type="text/javascript"></script> </head>`
Refer scripts from CDN	CSHTML `<head> ... <!--<script src="https://cdn.syncfusion.com/blazor/<Version>/<Component script name>" type="text/javascript"></script>--> <script src="https://cdn.syncfusion.com/blazor/21.1.35/sf-textbox.min.js" type="text/javascript"></script> </head>`

The following table lists components and its script reference.

Component	Script name
TextBox	sf-textbox.min.js
NumericTextBox	sf-numerictextbox.min.js
MaskedTextBox	sf-maskedtextbox.min.js
Uploader	sf-uploader.min.js
Calendar	sf-calendar.min.js
DatePicker	sf-datepicker.min.js
DateTimePicker	sf-datepicker.min.js
DateRangePicker	sf-daterangepicker.min.js
DiagramComponent	sf-diagramcomponent.min.js
TimePicker	sf-timepicker.min.js
AutoComplete	sf-dropdownlist.min.js
ComboBox	sf-dropdownlist.min.js
DropDownList	sf-dropdownlist.min.js
MultiSelect	sf-multiselect.min.js
DropDownButton	sf-drop-down-button.min.js
SplitButton	sf-drop-down-button.min.js
ProgressButton	sf-spinner.min.js
ListBox	sf-listbox.min.js
ColorPicker	sf-colorpicker.min.js
Signature	sf-signature.min.js
ContextMenu	sf-contextmenu.min.js
Menu	sf-menu.min.js
Breadcrumb	sf-breadcrumb.min.js
QueryBuilder	sf-querybuilder.min.js
Grid	sf-grid.min.js
Accordion	sf-accordion.min.js
Tab	sf-tab.min.js
Toolbar	sf-toolbar.min.js
Schedule	sf-schedule.min.js
BarcodeGenerator	sf-barcode.min.js
Maps	sf-maps.min.js
CircularGauge	sf-circulargauge.min.js
LinearGauge	sf-lineargauge.min.js
Chart	sf-chart.min.js
AccumulationChart	sf-accumulation-chart.min.js
StockChart	sf-stock-chart.min.js
BulletChart	sf-bullet-chart.min.js
Sparkline	sf-sparkline.min.js
TreeMap	sf-treemap.min.js
ProgressBar	sf-progressbar.min.js
SmithChart	sf-smith-chart.min.js
RangeNavigator	sf-range-navigator.min.js
HeatMap	sf-heatmap.min.js
FileManager	sf-filemanager.min.js
Slider	sf-slider.min.js
Tooltip	sf-tooltip.min.js
ListView	sf-listview.min.js
DashboardLayout	sf-dashboard-layout.min.js
Sidebar	sf-sidebar.min.js
TreeView	sf-treeview.min.js
PivotView	sf-pivotview.min.js
TreeGrid	sf-treegrid.min.js
Spinner	sf-spinner.min.js
Splitter	sf-splitter.min.js
Toast	sf-toast.min.js
Dialog	sf-dialog.min.js
RichTextEditor	sf-richtexteditor.min.js
InPlaceEditor	sf-inplaceeditor.min.js
Kanban	sf-kanban.min.js
Gantt	sf-gantt.min.js
PdfViewer	sf-pdfviewer.min.js
DocumentEditor	sf-documenteditor.min.js
Pager	sf-pager.min.js

Custom Resource Generator

The Syncfusion Blazor provides an option to generate a component’s interop scripts using the Custom Resource Generator (CRG) tool for the Blazor components. Refer here to generate the component-wise scripts externally using CRG.