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
- Blazor Server apps in .NET 6 or 7
- Blazor WebAssembly 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:
- Install the Telerik Blazor NuGet packages in your Blazor application.
- Register the required namespaces.
- Add the Telerik Blazor service.
- Add the CSS theme and JavaScript file.
- Add the
<TelerikRootComponent>
. - 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:
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.
@* 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
:
// 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.
builder.Services.AddTelerikBlazor();
To localize the Telerik Blazor components, always register your own
ITelerikStringLocalizer
service afterbuilder.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.
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.
<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:
- Register
telerik-blazor.js
in the<head>
of the web page with adefer
attribute. This allows the JavaScript file to load as a non-blocking resource together with the rest of the web page. - Set
autostart="false"
to the Blazor framework<script>
tag. -
Start the Blazor client-side framework in the
DOMContentLoaded
event.
<!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 Blazor Web Apps with Global interactivity location
- Blazor Server, WebAssembly and Hybrid apps in all .NET versions
If you have a .NET 8 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.
- Create a new layout file in the app, for example,
TelerikLayout.razor
. - Place the new layout in the same folder as the default application layout
MainLayout.razor
. - Add a
<TelerikRootComponent>
tag to the new layout and set@Body
as the root component's child content. - Make the new layout a parent of the default application 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.
<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.