Typical Workflow for Using the UI for Blazor Components
This article describes the steps in the typical workflow for using the Telerik UI for Blazor components—getting the Telerik UI for Blazor components and configuring your project to use them.
The information in this article is also available as step-by-step tutorials for Blazor Server, WebAssembly, .NET 8 Blazor Web App and Blazor Hybrid apps.
To use the Telerik UI for Blazor, you need to:
Get the Telerik Blazor packages in your project.
Add the client assets.
Set up the project to recognize the Telerik components.
Telerik-Specific Packages
Telerik UI for Blazor is distributed through NuGet packages. The following table represents the NuGet packages that comprise the Telerik UI for Blazor components suite.
NuGet Package Name | Description |
---|---|
Telerik.UI.for.Blazor |
The main package that contains the code for the UI components and the only package that you must reference explicitly. Adding the package to your project will automatically add the other necessary dependencies. |
Telerik.DataSource |
Contains code for working with data and is needed for data binding the UI for Blazor components. |
Telerik.Recurrence |
Contains code for working with recurring appointments, for example, in the Scheduler UI component. |
Telerik.Documents.SpreadsheetStreaming |
Contains code for working with spreadsheet documents and is used for exporting. |
Telerik.Zip |
Contains code for working with zip archives and excel files. Excel files are actually archives and this packages is required for exporting them. |
If you use a trial license, these package names have a
.Trial
suffix, for exampleTelerik.UI.for.Blazor.Trial
,Telerik.DataSource.Trial
, andTelerik.Recurrence.Trial
.
Getting the Telerik Packages
You can obtain the required UI for Blazor packages in four ways:
-
The private Telerik NuGet feed:
- Requires an Internet connection and authentication.
- It also informs you about updates and new versions.
-
- You can download it once from your Telerik account and then use it without an Internet connection.
- It allows you to install the VS extensions and use various templates for creating new projects and a wizard for enabling existing projects to use Telerik components.
- It does not provide information about new versions.
- Depending on your setup, it may require elevated privileges to run the installation wizard.
- It provides an offline version of the demos.
-
The ZIP archive package:
- You can download it once from your Telerik account and then use it without an Internet connection.
- It does not provide information about new versions and does not require installation.
- It provides an offline version of the demos.
-
The standalone
.nupkg
files:- They are the bare minimum that is required.
- To use them, follow the instructions for using the ZIP archive, but download the
.nupkg
files instead.
Adding the Client Assets
The Telerik UI for Blazor components require a Telerik stylesheet and a JS Interop file in the app's main index file. Depending on the Blazor hosting model and framework version, this index file will differ:
- For Client-Side and Blazor Hybrid apps, use the
wwwroot/index.html
file. - For Server-Side Blazor apps, use one of the following files:
-
~/Pages/_Layout.cshtml
for .NET 6 -
~/Pages/_Host.cshtml
for .NET 7
-
- For Web App projects targeting .NET 8, use the
~/Components/App.razor
.
To add these client assets, use either the static assets or the CDN method.
Using Static Assets
You can add the Telerik JS Interop file and the Telerik Stylesheet as static assets. Static assets (the _content
folder) are automatically included in the solution from the NuGet package during build, so all you need is to enable static assets as shown in the snippet below. The _content
folder is expanded by the framework into the local NuGet cache, and the project copies it from there.
To enable the use of static assets in your project, add the app.UseStaticFiles();
line to the Program.cs
file of your Server project (by default, this line is already present).
C#
var app = builder.Build();
// ...
//To enable static files from a package, make sure this is present.
app.UseStaticFiles();
// ...
app.Run();
Telerik Stylesheet
The stylesheet allows you to use one of the built-in Themes, for example, the Default theme:
<head>
. . .
<link rel="stylesheet" href="_content/Telerik.UI.for.Blazor/css/kendo-theme-default/all.css" />
<!-- For Trial licenses, use
<link rel="stylesheet" href="_content/Telerik.UI.for.Blazor.Trial/css/kendo-theme-default/all.css" />
-->
</head>
Telerik JS Interop File
The JS Interop file provides features that cannot be implemented with native Blazor.
<head>
. . .
<script src="_content/Telerik.UI.for.Blazor/js/telerik-blazor.js" defer></script>
<!-- For Trial licenses, use
<script src="_content/Telerik.UI.for.Blazor.Trial/js/telerik-blazor.js" defer></script>
-->
</head>
Using CDN
You can reference the built-in Telerik assets like the JS Interop file and the theme stylesheets from a cloud CDN instead of a local resource on your server.
- The Telerik UI for Blazor CDN distributes the most common swatches for each base theme.
- The additional Themes CDN distributes all available swatches for the built-in themes.
<!DOCTYPE html>
<html>
<head>
. . .
<!-- Choose only one of the themes -->
<link rel="stylesheet" href="https://blazor.cdn.telerik.com/blazor/5.1.1/kendo-theme-default/all.css" />
<!--
<link href="https://blazor.cdn.telerik.com/blazor/5.1.1/kendo-theme-bootstrap/all.css" rel="stylesheet" />
<link href="https://blazor.cdn.telerik.com/blazor/5.1.1/kendo-theme-material/all.css" rel="stylesheet" />
-->
<script src="https://blazor.cdn.telerik.com/blazor/5.1.1/telerik-blazor.min.js" defer></script>
</head>
. . .
</html>
Make sure that the version in the URLs matches the version of the Telerik UI for Blazor package.
If you decide to use a CDN over static assets, you may want to implement a fallback if the CDN is unavailable to your users.
Telerik recommends using static assets instead of a CDN. This approach relies on the static assets feature from the framework and takes the correct file from the package so you don't have to remember to update the CDN path when upgrading to a newer version.
Configuring the Project
To use the Telerik components, you must add a few items to your projects. Some of these items are common, while others depend on the project type (server-side or client-side), and the steps differ slightly in syntax. To configure the project:
Follow the Common Configuration instructions.
-
Follow the section for your project type:
Common Configuration
To make sure that the application will recognize the UI for Blazor components and that they will function correctly, add the required @using
statements and the TelerikRootComponent
.
Include @using Statements
You can set the project to recognize all Telerik components without explicit @using
statements on every .razor
file. To achieve this, add the following to your ~/_Imports.razor
file. You can register one or both icon namespaces, depending on the icon type you will be using.
@using Telerik.Blazor
@using Telerik.Blazor.Components
@using Telerik.FontIcons
@using Telerik.SvgIcons
Add the TelerikRootComponent
To use Telerik popups and global component settings, you must add the TelerikRootComponent
component at the root level of the app and configure the app layout to adopt that.
The configuration varies depending on the application type:
Client-side Project Specifics
The final step is to register the Telerik services. In a client-side Blazor project, you register services in the Program.cs
file of the WebAssembly (Client) project:
using ClientBlazorProject;
using Microsoft.AspNetCore.Components.Web;
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
// sample host builder for a WASM app, yours may differ
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) });
// Register the Telerik services.
builder.Services.AddTelerikBlazor();
await builder.Build().RunAsync();
Server-side Project Specifics
The final step is to register the Telerik services. In a server-side Blazor project, you register services in the Program.cs
file of your project.
C#
// ...
var builder = WebApplication.CreateBuilder(args);
// ...
builder.Services.AddTelerikBlazor();
// ...
var app = builder.Build();
Web App Project Specifics
The final step is to register the Telerik services. In a Blazor Web App project with interactive render mode Server, you register services in the Program.cs
file of your project.
For interactive render modes WebAssembly and Auto, register the service in the Program.cs
file of both the server and client project.
C#
// ...
var builder = WebApplication.CreateBuilder(args);
// ...
builder.Services.AddTelerikBlazor();
// ...
var app = builder.Build();
Blazor Hybrid Project Specifics
The final step is to register the Telerik services. In a Hybrid Blazor project, you register services in the MauiProgram.cs
file of the project:
C#
public static MauiApp CreateMauiApp()
{
var builder = MauiApp.CreateBuilder();
builder
.UseMauiApp<App>()
.ConfigureFonts(fonts =>
{
fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
});
builder.Services.AddMauiBlazorWebView();
// Register the Telerik services.
builder.Services.AddTelerikBlazor();
var host = builder.Build();
return host;
}