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 and WebAssembly 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/_Host.cshtml
for .NET 3.x -
~/Pages/_Layout.cshtml
for .NET 6
-
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 startup file of your Server project (by default, this line is already present):
-
Startup.cs
for .NET 3.x and .NET 5 -
Program.cs
for .NET 6
C#
var app = builder.Build();
// ...
//To enable static files from a package, make sure this is present.
app.UseStaticFiles();
// ...
app.Run();
namespace MyBlazorAppName
{
public class Startup
{
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
// ...
//To enable static files from a package, make sure this is present.
app.UseStaticFiles();
// ...
}
}
}
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/4.5.0/kendo-theme-default/all.css" />
<!--
<link href="https://blazor.cdn.telerik.com/blazor/4.5.0/kendo-theme-bootstrap/all.css" rel="stylesheet" />
<link href="https://blazor.cdn.telerik.com/blazor/4.5.0/kendo-theme-material/all.css" rel="stylesheet" />
-->
<script src="https://blazor.cdn.telerik.com/blazor/4.5.0/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
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.
_Imports.razor
@using Telerik.Blazor
@using Telerik.Blazor.Components
@using Telerik.FontIcons
@using Telerik.SvgIcons
To enable the use of detached popups (for example, dropdown lists, menus, grid filters, etc.), you must add a TelerikLayout.razor
component at the root level of the DOM:
1. Next to your main layout file (by default, the ~/Shared/MainLayout.razor
file in the Blazor project), add a Razor component called TelerikLayout.razor
with the following content:
@inherits LayoutComponentBase
<TelerikRootComponent>
@Body
</TelerikRootComponent>
2. In the main layout file (by default, the ~/Shared/MainLayout.razor
file in the Blazor project), add @layout TelerikLayout
as the first line in the file. This will ensure that the TelerikRootComponent
wraps all the content in the MainLayout
.
@layout TelerikLayout
@inherits LayoutComponentBase
@* @Body and other code will be present here depending on your project *@
Alternatively, the
TelerikRootComponent
can reside directly in theMainLayout
, but it must wrap all the other content, otherwise popups may display at the wrong position. Placing theTelerikRootComponent
in a separate Razor file helps for a better separation of concerns.
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 startup file of your project which varies depending on the used .NET version:
-
Startup.cs
for .NET 3.x and .NET 5 -
Program.cs
for .NET 6
C#
// ...
var builder = WebApplication.CreateBuilder(args);
// ...
builder.Services.AddTelerikBlazor();
// ...
var app = builder.Build();
namespace MyBlazorAppName
{
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
// ...
services.AddTelerikBlazor();
}
// ...
}
}
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;
}