Reference scripts in Blazor Application

29 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.

    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.

    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.

    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.

    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.

    See also