Getting Started

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 and WebAssembly 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 Blazor 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.

<!DOCTYPE html>
<html>
<head>
    . . .
    <!-- Choose only one of the themes -->

    <link rel="stylesheet" href="https://blazor.cdn.telerik.com/blazor/4.1.0/kendo-theme-default/all.css" />

    <!-- 
        <link href="https://blazor.cdn.telerik.com/blazor/4.1.0/kendo-theme-bootstrap/all.css" rel="stylesheet" />
        <link href="https://blazor.cdn.telerik.com/blazor/4.1.0/kendo-theme-material/all.css" rel="stylesheet" />
    -->

    <script src="https://blazor.cdn.telerik.com/blazor/4.1.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:

  1. Follow the Common Configuration instructions.

  2. 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 the MainLayout, but it must wrap all the other content, otherwise popups may display at the wrong position. Placing the TelerikRootComponent 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();

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Microsoft.Extensions.DependencyInjection;
using System.Threading.Tasks;
using System.Net.Http;
using System;

namespace ClientBlazorProject.Client // Make sure this matches your actual WASM project namespace.
{
    public class Program
    {
        public static async Task Main(string[] args)
        {
            // sample host builder for a WASM app, yours may differ
            var builder = WebAssemblyHostBuilder.CreateDefault(args);
            builder.RootComponents.Add<App>("app");
            builder.Services.AddScoped(sp => new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) });
            // There may be more code here.

            // Register the Telerik services.
            builder.Services.AddTelerikBlazor();

            // There may be more code here.
            // sample host builder for a WASM app, yours may differ
            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();
        }

        // ...
    }
}

Next Steps

See Also

In this article
Related articles
Not finding the help you need? Improve this article