Workflow Details for Using the Telerik UI for Blazor Components

This article describes the required steps to use the Telerik UI for Blazor components in any kind of Blazor application and any .NET version. The content below describes how to obtain the Telerik UI for Blazor components and configure your project to use them.

The information in this article builds on top of the step-by-step tutorials for specific Blazor application types or render modes:

• Blazor Web App template in .NET 8 or 9
• Blazor WebAssembly Standalone apps
• Blazor Server apps in .NET 6 or 7

• Blazor Hybrid (MAUI) apps

  The differences between the above tutorials and this page are:

• The above tutorials are simpler to follow and are suitable for first-time Blazor or Telerik component users.

• The current article assumes some Blazor experience and knowledge about the Blazor application structure.
• The above tutorials describe the fastest and simplest way to get started with Telerik UI for Blazor.

• The current article provides more setup options and suggests possible enhancements.

  It's best for first-time users to start from the above tutorials and then come back to this article. Developers who have already setup Telerik Blazor apps can use directly this article.

The required milestones to obtain and use Telerik UI for Blazor are:

1. Install the Telerik Blazor NuGet packages in your Blazor application.
2. Register the required namespaces.
3. Add the Telerik Blazor service.
4. Add the CSS theme and JavaScript file.
5. Add the <TelerikRootComponent>.
6. Add components to a view.

NuGet Packages

Telerik UI for Blazor is distributed through several private and public NuGet packages. The content below lists them all and explains how to obtain them.

Telerik.UI.for.Blazor is the only NuGet package that you must reference in the app. This package references all others as dependencies.

NuGet Package Name	Description
Telerik.UI.for.Blazor	Contains the main code of the UI components. Required for all Telerik UI for Blazor applications.
Telerik.SvgIcons	Contains all Telerik SVG icons. Available on nuget.org.
Telerik.FontIcons	Contains all Telerik font icons. Available on nuget.org.
Telerik.DataSource	Adds support for data operations. All databound UI components use it for paging, sorting, filtering, or grouping.
Telerik.Recurrence	Adds support for recurring appointments in the Scheduler component.
Telerik.Documents.SpreadsheetStreaming	Adds support for working with spreadsheet documents, and exporting to Excel or CSV. This package is part of Telerik Document Processing.
Telerik.Zip	Contains code for working with ZIP archives and Excel files. Excel files are actually ZIP archives and this package takes part in the exporting process. This package is part of Telerik Document Processing.
Telerik.Pivot.Core	Contains base code for the PivotGrid component. This NuGet package must not be used separately without the Telerik PivotGrid component.
Telerik.Pivot.DataProviders.Xmla	Adds support for data binding the PivotGrid component to XMLA. This NuGet package must not be used separately without the Telerik PivotGrid component.

If you use a trial license, the private package names have a .Trial suffix, for example, Telerik.UI.for.Blazor.Trial.

Getting the Telerik NuGet Packages

To get the two public icon packages, you only need the default NuGet package source nuget.org. To use a local NuGet feed, download the packages from:

• Telerik.SvgIcons
• Telerik.FontIcons

You can get the private Telerik UI for Blazor packages in four ways:

• Telerik NuGet package source. This is usually the most convenient option, and your NuGet client will notify you about new component versions. The other options below can be useful as an emergency alternative, or in environments with restricted Internet connection.
• Automated installer
• ZIP archive
• As standalone .nupkg files. To use them, follow the instructions at ZIP archive, but download the .nupkg files instead.

Always check the Telerik UI for Blazor release notes when updating the components. New major versions can contain breaking changes.

Namespaces

The .NET compiler requires several Telerik namespaces to recognize the Telerik Blazor components and set some of the component parameters.

There are a few other optional namespaces that may be needed often. You can import them globally for your convenience.

_Imports.razor

@* required *@
@using Telerik.Blazor // set component parameters
@using Telerik.Blazor.Components // recognize components tags
@using Telerik.SvgIcons // use SVG icons
@using Telerik.FontIcons // use font icons

@* optional *@
@using Telerik.DataSource // implement data-related programmatic customizations
@using Telerik.DataSource.Extensions // use OnRead events and ToDataSourceResult()

To avoid the need to register Telerik namespaces in .cs files, use global using:

Program.cs or MauiProgram.cs

// required
global using Telerik.Blazor; // use component parameter values
global using Telerik.Blazor.Components; // use component types and instances
global using Telerik.SvgIcons; // use SVG icons
global using Telerik.FontIcons; // use font icons

// optional
global using Telerik.DataSource; // implement data-related programmatic customizations
global using Telerik.DataSource.Extensions; // use OnRead events and ToDataSourceResult()

Service

The Telerik Blazor service provides component localization and registers the default service that implements ITelerikStringLocalizer.

The Telerik Blazor components render all their built-in labels through this localization mechanism for consistency, even when .NET localization is not used.

Register the Telerik service in all projects that use Telerik Blazor components.

Program.cs or MauiProgram.cs

builder.Services.AddTelerikBlazor();

To localize the Telerik Blazor components, always register your own ITelerikStringLocalizer service after builder.Services.AddTelerikBlazor();.

CSS Theme and JavaScript Files

The Telerik UI for Blazor components require a theme stylesheet and a JSInterop file.

To use static CSS and JS assets from the NuGet package in a project, make sure that the project has app.UseStaticFiles(); in its Program.cs file. This is true by default.

You can also add the Telerik UI for Blazor version number to the CSS and JavaScript file URLs to prevent browser caching during version upgrades.

CSS Theme

Register the Telerik theme stylesheet in the <head> of the web page. Add the theme before the application stylesheet and the CSS isolation stylesheet. This CSS file order lets you override Telerik theme styles more easily, if necessary.

Register the Telerik font icon stylesheet only if the app uses Telerik font icons.

Adding the Telerik Blazor CSS files

<head>
    <link rel="stylesheet" href="_content/Telerik.UI.for.Blazor/css/kendo-theme-default/all.css" />
    <!-- When using a Trial license -->
    <!--<link rel="stylesheet" href="_content/Telerik.UI.for.Blazor.Trial/css/kendo-theme-default/all.css" />-->

    <!-- Add only if using font icons -->
    <!--<link href="_content/Telerik.UI.for.Blazor/css/kendo-font-icons/font-icons.css" rel="stylesheet" />-->
    <!-- When using a Trial license -->
    <!--<link href="_content/Telerik.UI.for.Blazor.Trial/css/kendo-font-icons/font-icons.css" rel="stylesheet" />-->

    <!-- main application stylesheet -->
    <link rel="stylesheet" href="css/app.css" />
    <!-- CSS isolation stylesheet -->
    <link rel="stylesheet" href="AppName.styles.css"  />
</head>

JavaScript File

Telerik Blazor components rely on a JavaScript JSInterop file for some interactive features and communication between the .NET runtime and the web page.

The recommended way to register the Telerik Blazor JS file for better loading performance and reliable Blazor startup is:

1. Register telerik-blazor.js in the <head> of the web page with a defer attribute. This allows the JavaScript file to load as a non-blocking resource together with the rest of the web page.
2. Set autostart="false" to the Blazor framework <script> tag.
3. Start the Blazor client-side framework in the DOMContentLoaded event.

Adding the Telerik Blazor JavaScript file

<!DOCTYPE html>
<html>
<head>
   <script src="_content/Telerik.UI.for.Blazor/js/telerik-blazor.js" defer></script>
   <!-- When using a Trial license -->
   <!--<script src="_content/Telerik.UI.for.Blazor.Trial/js/telerik-blazor.js" defer></script>-->
</head>
<body>
   <script src="_framework/blazor.web.js" autostart="false"></script>
   <script>
      document.addEventListener("DOMContentLoaded", function () {
         Blazor.start();
      });
   </script>
</body>
</html>

All the information in this section also applies when using the Telerik CDN. However, Telerik recommends using static assets, as shown above. Remote asset URLs require a CDN fallback and manual maintenance during component version updates.

TelerikRootComponent

The TelerikRootComponent is a special component in Telerik UI for Blazor:

• It can apply settings to all other Telerik Blazor components in the application.
• It renders all component popups. All Telerik Blazor components that use popups will throw an exception if they cannot detect the TelerikRootComponent.

The TelerikRootComponent placement depends on the interactivity location of the Blazor app. The component should reside in a layout file, but only if the layout file supports interactive render mode.

The instructions and code example below apply to:

• .NET 8 or 9 Blazor Web Apps with Global interactivity location
• Blazor Server, WebAssembly and Hybrid apps in all .NET versions

If you have a Blazor Web App with Per page/component interactivity location, then the correct TelerikRootComponent usage is different. The component still needs to wrap all other Telerik components, but it cannot reside in a static layout file, because the other Telerik component will not detect it. Refer to section Interactivity Considerations and article Using TelerikRootComponent with Per Page/Component Interactivity.

Optimal TelerikRootComponent Usage

Add a <TelerikRootComponent> component in the topmost layout file of the Blazor application. The TelerikRootComponent should enclose all the layout file content and all visible content on the web page. This setup ensures correct popup position and correct propagation of global settings to all Telerik Blazor components in the app.

1. Create a new layout file in the app, for example, TelerikLayout.razor.
2. Place the new layout in the same folder as the default application layout MainLayout.razor.
3. Add a <TelerikRootComponent> tag to the new layout and set @Body as the root component's child content.
4. Make the new layout a parent of the default application layout.

Adding TelerikRootComponent to a new layout

@inherits LayoutComponentBase

<TelerikRootComponent>
    @Body
</TelerikRootComponent>

@inherits LayoutComponentBase
@layout TelerikLayout

@* The other MainLayout.razor content remains the same. *@

Check the TelerikRootComponent documentation for more information about its purpose and usage.

Add Telerik Components to a View

The Blazor application is ready to use Telerik components.

Home.razor

<TelerikButton OnClick="@OnButtonClick">
    Telerik Blazor Button
</TelerikButton>

@ButtonClickLog

@code {
    private string ButtonClickLog { get; set; } = string.Empty;

    private void OnButtonClick()
    {
        ButtonClickLog = $"Button clicked at {DateTime.Now.ToString("HH:mm:ss.fff")}.";
    }
}

Next Steps

• Check the list of available components.
• Explore the live Telerik UI for Blazor demos.
• Learn the data binding fundamentals for Telerik UI for Blazor components.
• Get started with the data Grid.
• Review the built-in themes or create custom ones.

See Also

• Automated MSI installer
• ZIP archive
• Prevent browser caching during version upgrades
• JavaScript error troubleshooting
• NuGet troubleshooting