New to Telerik UI for Blazor? Download free 30-day trial

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:

  1. Get the Telerik Blazor packages in your project.

  2. Add the client assets.

  3. 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 example Telerik.UI.for.Blazor.Trial, Telerik.DataSource.Trial, and Telerik.Recurrence.Trial.

Getting the Telerik Packages

You can obtain the required UI for Blazor packages in four ways:

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.

<!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:

  1. Follow the Common Configuration instructions.

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

_Imports.razor

@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;
}

Next Steps

See Also

In this article