# Workflow Details for Using 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.

> tip The information in this article builds on top of the [Quick Start with Telerik UI for Blazor](https://www.telerik.com/blazor-ui/documentation/getting-started/web-app) tutorial.
>
> The differences between the above tutorial and this page are:
>
> * The above First Steps tutorial describes the fastest and simplest way to get started with Telerik UI for Blazor. It is suitable for first-time Blazor or Telerik component users.
>
> * The current Workflow Details article assumes some Blazor experience and knowledge about the Blazor application structure. It requires manual configuration steps that help you learn about Telerik UI for Blazor in more depth.
>
> It's best for first-time users to start from the [Getting Started tutorial](https://www.telerik.com/blazor-ui/documentation/getting-started/web-app) and then come back to this article. Developers who have already set up Telerik Blazor apps can use this article.

The required milestones to obtain and use Telerik UI for Blazor are:

1. Install the [Telerik Blazor NuGet packages](https://www.telerik.com/blazor-ui/documentation/getting-started/workflow-details#nuget-packages) in your Blazor application.
2. Install a [Telerik license key](https://www.telerik.com/blazor-ui/documentation/getting-started/workflow-details#license-key).
3. Register the [required namespaces](https://www.telerik.com/blazor-ui/documentation/getting-started/workflow-details#namespaces).
4. Add the [Telerik Blazor service](https://www.telerik.com/blazor-ui/documentation/getting-started/workflow-details#service).
5. Add the [CSS theme and JavaScript file](https://www.telerik.com/blazor-ui/documentation/getting-started/workflow-details#css-theme-and-javascript-files).
6. Add the [`<TelerikRootComponent>`](https://www.telerik.com/blazor-ui/documentation/getting-started/workflow-details#telerikrootcomponent).
7. [Add components to a view](https://www.telerik.com/blazor-ui/documentation/getting-started/workflow-details#add-telerik-components-to-a-view).
8. Install the [Telerik Blazor AI Tools](https://www.telerik.com/blazor-ui/documentation/getting-started/workflow-details#install-the-telerik-ai-tools).

## NuGet Packages

Telerik UI for Blazor is distributed through NuGet packages. The content below lists them all and explains how to obtain them.

> tip `Telerik.UI.for.Blazor` is the only NuGet package that you must reference in the app. This package references all others as dependencies, except the optional `Telerik.UI.for.Blazor.DatAInsightsComposer`.

> tip Starting from Telerik UI for Blazor version **14.0.0**, all required NuGet packages are [available on `nuget.org`](https://www.nuget.org/profiles/Progress).

<style>
    .article table {
        table-layout: auto;
        word-break: normal;
    }
</style>

| NuGet Package Name                                                                                                        | Description                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`Telerik.UI.for.Blazor`](https://www.nuget.org/packages/Telerik.UI.for.Blazor)                                           | Contains the main code of the UI components. Required for all Telerik UI for Blazor applications.                                                                                                                                                                                                           |
| [`Telerik.Licensing`](https://www.nuget.org/packages/Telerik.Licensing)                                                   | Verifies the licensing status of the developer during app build. Requires a [license key](https://www.telerik.com/blazor-ui/documentation/getting-started/workflow-details#license-key).                                                                                                                    |
| [`Telerik.SvgIcons`](https://www.nuget.org/packages/Telerik.SvgIcons)                                                     | Contains all Telerik SVG icons.                                                                                                                                                                                                                                                                             |
| [`Telerik.FontIcons`](https://www.nuget.org/packages/Telerik.FontIcons)                                                   | Contains all Telerik font icons.                                                                                                                                                                                                                                                                            |
| [`Telerik.DataSource`](https://www.nuget.org/packages/Telerik.DataSource)                                                 | Adds support for data operations. All databound UI components use it for paging, sorting, filtering, or grouping.                                                                                                                                                                                           |
| [`Telerik.Recurrence`](https://www.nuget.org/packages/Telerik.Recurrence)                                                 | Adds support for recurring appointments in the [Scheduler component](https://www.telerik.com/blazor-ui/documentation/components/scheduler/overview).                                                                                                                                                        |
| [`Telerik.Documents.SpreadsheetStreaming`](https://www.nuget.org/packages/Telerik.Documents.SpreadsheetStreaming)         | Adds support for working with spreadsheet documents, and exporting to Excel or CSV. This package is part of [Telerik Document Processing](https://www.telerik.com/blazor-ui/documentation/integrations/document-processing-libraries).                                                                      |
| [`Telerik.Zip`](https://www.nuget.org/packages/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](https://www.telerik.com/blazor-ui/documentation/integrations/document-processing-libraries). |
| [`Telerik.UI.for.Blazor.DatAInsightsComposer`](https://www.nuget.org/packages/Telerik.UI.for.Blazor.DatAInsightsComposer) | Contains the [Telerik DatAInsightsComposer component](https://www.telerik.com/blazor-ui/documentation/components/datainsightscomposer/overview). The package is optional.                                                                                                                                   |
| [`Telerik.Pivot.Core`](https://www.nuget.org/packages/Telerik.Pivot.Core)                                                 | Contains base code for the [PivotGrid component](https://www.telerik.com/blazor-ui/documentation/components/pivotgrid/overview). This NuGet package must not be used separately without the Telerik PivotGrid component.                                                                                    |
| [`Telerik.Pivot.DataProviders.Xmla`](https://www.nuget.org/packages/Telerik.Pivot.DataProviders.Xmla)                     | Adds support for [data binding the PivotGrid component to XMLA](https://www.telerik.com/blazor-ui/documentation/components/pivotgrid/data-binding). This NuGet package must not be used separately without the Telerik PivotGrid component.                                                                 |

### Getting the Telerik NuGet Packages

You can get the Telerik UI for Blazor packages and their dependencies in four ways:

* [`nuget.org`](https://www.nuget.org/profiles/Progress). 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.
* [Telerik private NuGet package source](https://www.telerik.com/blazor-ui/documentation/installation/nuget)—use only for Telerik UI for Blazor versions **13.3.0** and older. Note that the icon and licensing packages must be downloaded from `nuget.org`, regardless of the Telerik UI for Blazor version.
* [Automated installer](https://www.telerik.com/blazor-ui/documentation/installation/automated)
* [ZIP archive](https://www.telerik.com/blazor-ui/documentation/installation/zip)
* As standalone `.nupkg` files. To use them, follow the instructions at [ZIP archive](https://www.telerik.com/blazor-ui/documentation/installation/zip), but download the `.nupkg` files instead.

> Always check the [Telerik UI for Blazor release notes](https://www.telerik.com/support/whats-new/blazor-ui/release-history) when updating the components. New [major versions can contain breaking changes](https://www.telerik.com/blazor-ui/documentation/upgrade/breaking-changes/list).

## License Key

> tip This documentation section applies to Telerik UI for Blazor version **8.0.0** and above. Older versions do not require a license key.

To download and install your Telerik license key:

1. Go to the <a href="https://www.telerik.com/account/your-licenses/license-keys" target="_blank">License Keys page</a> in your Telerik account.
2. Click the **Download License Key** button.
3. Save the `telerik-license.txt` file to:
   * (on Windows) `%AppData%\Telerik\telerik-license.txt`, for example, `C:\Users\...\AppData\Roaming\Telerik\telerik-license.txt`
   * (on Mac or Linux) `~/.telerik/telerik-license.txt`, for example, `/Users/.../.telerik/telerik-license.txt`

This will make the license key available to all Telerik .NET apps that you develop on your local machine.

The [Telerik License Key](https://www.telerik.com/blazor-ui/documentation/installation/license-key) article provides additional details on installing and updating your Telerik license key in different scenarios. [Automatic license key maintenance](https://www.telerik.com/blazor-ui/documentation/installation/license-key#automatic-installation) is more effective and recommended in the long run.

## Interactive Render Mode

This section applies to Blazor Web Apps. It is not relevant to Blazor WebAssembly Standalone apps or Blazor Hybrid apps.

Telerik UI for Blazor requires interactive render mode. Using [**Global** Interactivity location](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-9.0#apply-a-render-mode-to-the-entire-app) is highly recommended, as it ensures easier setup and usage of the Telerik components.

The Telerik Blazor components will not respond to user actions and the Blazor framework will not refresh their UI in [Static server-side rendering mode (static SSR)](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-9.0#static-server-side-rendering-static-ssr). Telerik Blazor components with JavaScript rendering (Barcodes, Charts, Gauges, Maps, and QR Codes) will not render in static SSR at all.

Use the host and startup files that match the application hosting model. A Blazor Web App uses `App.razor`, an interactive render mode such as `InteractiveServer`, and `blazor.web.js`. A Blazor WebAssembly Standalone app uses its `index.html` host and the WebAssembly framework script. Do not combine the document and startup configuration from these two hosting models. If Telerik components render but do not respond to clicks, verify the render mode before troubleshooting component events.

The `Account` section in the Blazor Web App template with identity is static by design. Most Telerik Blazor components cannot work in this section.

Authentication with ASP.NET Core Identity and authorization for routable pages are application-level concerns. Use the Blazor [`[Authorize]` attribute](https://learn.microsoft.com/en-us/aspnet/core/blazor/security/?view=aspnetcore-9.0#authorize-attribute) and [`AuthorizeRouteView`](https://learn.microsoft.com/en-us/aspnet/core/blazor/security/?view=aspnetcore-9.0#customize-unauthorized-content-with-the-router-component) to protect pages, and keep interactive Telerik components outside the static `Account` section. Telerik components do not require a separate authentication configuration.

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

> caption \_Imports.razor

```RAZOR.skip-repl
@* required *@
@using Telerik.Blazor // recognize event arguments and component parameter values
@using Telerik.Blazor.Components // recognize component tags and instance types

@using Telerik.SvgIcons // use SVG icons
@* or *@
@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`](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/using-directive#global-modifier):

> caption Program.cs or MauiProgram.cs

```C#.skip-repl
// required
global using Telerik.Blazor; // recognize event arguments and component parameter values
global using Telerik.Blazor.Components; // recognize component tags and instance types

global using Telerik.SvgIcons; // use SVG icons
@* or *@
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](https://www.telerik.com/blazor-ui/documentation/globalization/localization) and registers the default service that implements [`ITelerikStringLocalizer`](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.services.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.

> caption Program.cs or MauiProgram.cs

```C#.skip-repl
builder.Services.AddTelerikBlazor();
```

> To [localize the Telerik Blazor components](https://www.telerik.com/blazor-ui/documentation/globalization/localization), always register your own `ITelerikStringLocalizer` service **after** `builder.Services.AddTelerikBlazor();`.

## CSS Theme and JavaScript Files

The Telerik UI for Blazor components require a [theme stylesheet](https://www.telerik.com/blazor-ui/documentation/getting-started/workflow-details#css-theme) and a [JSInterop file](https://www.telerik.com/blazor-ui/documentation/getting-started/workflow-details#javascript-file).

To use static CSS and JS assets from the NuGet package in a project, make sure that the [project allows it](https://learn.microsoft.com/en-us/aspnet/core/blazor/fundamentals/static-files), which is true by default. To [prevent browser caching of the Telerik static NuGet assets during version upgrades](https://www.telerik.com/blazor-ui/documentation/knowledge-base/common-browser-cache-buster):

* In .NET 9 and later versions, you can use `MapStaticAssets()` in `Program.cs` and `@Assets["..."]` in `App.razor`.
* Add the Telerik UI for Blazor version number to the CSS and JavaScript file URLs.

### CSS Theme

Register the [Telerik theme stylesheet](https://www.telerik.com/blazor-ui/documentation/styling-and-themes/overview) in the `<head>` of the web page. Add the theme before the application stylesheet and the [CSS isolation stylesheet](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/css-isolation). This CSS file order lets you [override Telerik theme styles](https://www.telerik.com/blazor-ui/documentation/styling-and-themes/override-theme-styles) more easily, if necessary.

Register the [Telerik font icon stylesheet](https://www.telerik.com/blazor-ui/documentation/common-features/icons#font-icon-stylesheet) only if the app uses [Telerik font icons](https://www.telerik.com/blazor-ui/documentation/common-features/icons).

Set a `k-body` CSS class to the `<body>` element to apply typography, text color, and background color to the whole page, depending on the Telerik theme. The `k-body` class is crucial when using dark [theme swatches](https://www.telerik.com/blazor-ui/documentation/styling-and-themes/overview#what-is-a-swatch).

> caption Adding the Telerik Blazor CSS files

```HTML.skip-repl
<head>
    
    <link rel="stylesheet" href="_content/Telerik.UI.for.Blazor/css/kendo-theme-default/all.css" />

    
    

    
    <link rel="stylesheet" href="css/app.css" />
    
    <link rel="stylesheet" href="AppName.styles.css"  />
</head>

<body class="k-body">

</body>
```

### 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](https://learn.microsoft.com/en-us/aspnet/core/blazor/fundamentals/startup) is:

1. Register `telerik-blazor.js` in the `<head>` of the web page with a `defer` attribute. This allows the JavaScript file to load as a non-blocking resource together with the rest of the web page.
2. Set `autostart="false"` to the Blazor framework `<script>` tag.
3. [Start the Blazor client-side framework in the `DOMContentLoaded` event](https://learn.microsoft.com/en-us/aspnet/core/blazor/fundamentals/startup?view=aspnetcore-8.0#initialize-blazor-when-the-document-is-ready).

> caption Adding the Telerik Blazor JavaScript file

```HTML.skip-repl
<!DOCTYPE html>
<html>
<head>
   <script src="_content/Telerik.UI.for.Blazor/js/telerik-blazor.js" defer></script>
</head>
<body class="k-body">
   <script src="_framework/blazor.web.js" autostart="false"></script>
   <script>
      document.addEventListener("DOMContentLoaded", function () {
         Blazor.start();
      });
   </script>
</body>
</html>
```

> tip All the information in this section also applies when using the [Telerik CDN](https://www.telerik.com/blazor-ui/documentation/common-features/cdn). However, Telerik recommends using static assets, as shown above. Remote asset URLs require a [CDN fallback](https://www.telerik.com/blazor-ui/documentation/knowledge-base/cdn-fallback) and manual maintenance during [component version updates](https://www.telerik.com/blazor-ui/documentation/upgrade/overview).

## TelerikRootComponent

The [`TelerikRootComponent` is a special component](https://www.telerik.com/blazor-ui/documentation/components/rootcomponent/overview#purpose) 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 Blazor app hosting model and interactivity location. 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:
>
> * Blazor Web Apps with **Global** interactivity location
> * Blazor WebAssembly Standalone and Blazor Hybrid apps
>
> If you have a 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 components will not detect it](https://www.telerik.com/blazor-ui/documentation/knowledge-base/common-component-requires-telerikrootcomponent). Refer to section [Interactivity Considerations](https://www.telerik.com/blazor-ui/documentation/components/rootcomponent/overview#interactivity-considerations) and article [Using TelerikRootComponent with Per Page/Component Interactivity](https://www.telerik.com/blazor-ui/documentation/components/rootcomponent/per-component-interactivity-location).

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

1. Create a new layout file in the app, for example, `TelerikLayout.razor`.
2. Place the new layout in the same folder as the default application layout `MainLayout.razor`.
3. Add a `<TelerikRootComponent>` tag to the new layout and set `@Body` as the root component's child content.
4. Make the new layout a parent of the default application layout.

> caption Adding TelerikRootComponent to a new layout

```RAZOR.skip-repl TelerikLayout.razor
@inherits LayoutComponentBase

<TelerikRootComponent>
    @Body
</TelerikRootComponent>
```

```RAZOR MainLayout.razor
@inherits LayoutComponentBase
@layout TelerikLayout

@* The other MainLayout.razor content remains the same. *@
```

Check the [`TelerikRootComponent` documentation](https://www.telerik.com/blazor-ui/documentation/components/rootcomponent/overview) for more information about its purpose and usage.

## Add Telerik Components to a View

The Blazor application is ready to use Telerik components. For example, add a `TelerikButton` component in `Home.razor`:

> caption Home.razor

```RAZOR
<TelerikButton OnClick="@OnButtonClick">
    Telerik Blazor Button
</TelerikButton>

<p>@ButtonClickLog</p>

@code {
    private string ButtonClickLog { get; set; } = string.Empty;

    private void OnButtonClick()
    {
        ButtonClickLog = $"Telerik Button clicked at {DateTime.Now.ToString("HH:mm:ss.fff")}.";
    }
}
```

## Install the Telerik AI Tools

Telerik UI for Blazor provides AI-powered development assistance through a unified [MCP (Model Context Protocol) server](https://www.telerik.com/blazor-ui/documentation/ai/overview) that delivers intelligent, context-aware help directly in your IDE. The MCP server automatically recognizes your Telerik license and activates the available tools:

* [Agentic UI Generator](https://www.telerik.com/blazor-ui/documentation/ai/agentic-ui-generator/getting-started)—Build complete, production-ready UIs using natural language prompts. Describe your desired page, layout, or component configuration, and the AI-powered generator will create responsive, styled Blazor code with proper Telerik UI for Blazor component integration.

This unified MCP server integrates seamlessly with your IDE to provide contextual help and automate repetitive tasks, making it easier to explore the library and build feature-rich applications faster. Give the AI tools a try as you follow this guide or build your next project!

## Next Steps

<article-card-container>
    <article-card
        href="/ai/overview"
        src="/blazor-ui/documentation/assets/1a95789349616f5a96ee349e0f03d262/chat_light_large.svg"
        title="Use Telerik AI Tools"
        darkSrc="/blazor-ui/documentation/assets/92205189ccd98ce83506bf206bddeeee/chat_dark_large.svg"
        description="Telerik UI for Blazor provides AI-powered development assistance through a unified MCP server that delivers intelligent, context-aware help directly in your IDE.">
    </article-card>
    <article-card
        href="/introduction#list-of-components"
        src="/blazor-ui/documentation/assets/34f07dcdfb06e61deacd0ae611ead0fe/editor_ai_integration_light_large.svg"
        title="Use Components"
        darkSrc="/blazor-ui/documentation/assets/5afbc2e3509e38a68fa2c0e148bc4e84/editor_ai_integration_dark_large.svg"
        description="Check the list of available Telerik Blazor components.">
    </article-card>
    <article-card
        href="https://demos.telerik.com/blazor-ui"
        src="/blazor-ui/documentation/assets/ef4e202163f8ba624ebe354cb8e2552b/grid_ai_chat_integration_light_large.svg"
        title="Browse Online Demos"
        darkSrc="/blazor-ui/documentation/assets/90e1c198dfd43aaf9faecb945f01dbe0/grid_ai_chat_integration_dark_large.svg"
        description="Explore the live Telerik UI for Blazor examples.">
    </article-card>
    <article-card
        href="/common-features/data-binding/overview"
        src="/blazor-ui/documentation/assets/97bf251c25d62741f119c17febd0aa5c/ai_column_assistant_light_large.svg"
        title="Learn Telerik Data Binding"
        darkSrc="/blazor-ui/documentation/assets/14d39c54f99f4a661e9ef641b95d3610/ai_column_assistant_dark_large.svg"
        description="Learn the data binding fundamentals for Telerik UI for Blazor components.">
    </article-card>
    <article-card
        href="/components/grid/overview"
        src="/blazor-ui/documentation/assets/72271b5c70f640266b01ed7c4b13d6a5/ai_data_highlight_light_large.svg"
        title="Get Started with Data Grid"
        darkSrc="/blazor-ui/documentation/assets/96fcc5790687fb5ebf46c7fde8006ff9/ai_data_highlight_dark_large.svg"
        description="Bind the Telerik Blazor Grid to data and choose from the large variety of built-in features.">
    </article-card>
    <article-card
        href="/styling-and-themes/overview"
        src="/blazor-ui/documentation/assets/16321f5a65c2a527641999ce3ccfa3a1/aiprompt_light_large.svg"
        title="Create Themes"
        darkSrc="/blazor-ui/documentation/assets/fd20d47973fa3004bcf03f1cc2bcbff3/aiprompt_dark_large.svg"
        description="Review the built-in themes, customize them, or create your own.">
    </article-card>
</article-card-container>

## See Also

* [Automated MSI installer](https://www.telerik.com/blazor-ui/documentation/installation/automated)
* [ZIP archive](https://www.telerik.com/blazor-ui/documentation/installation/zip)
* [Prevent browser caching during version upgrades](https://www.telerik.com/blazor-ui/documentation/knowledge-base/common-browser-cache-buster)
* [JavaScript error troubleshooting](https://www.telerik.com/blazor-ui/documentation/troubleshooting/js-errors)
* [NuGet troubleshooting](https://www.telerik.com/blazor-ui/documentation/troubleshooting/nuget-feed)