First Steps with UI for Blazor in a Web App

This article explains how to use the Telerik UI for Blazor components into a .NET 8 Blazor Web App project template. You will create a new application from scratch, learn how to add the UI for Blazor components to a project, and finally, add a UI component to a view.

This step-by-step tutorial starts with the basics. If you are already familiar with the Telerik NuGet Feed and Blazor in general, you may prefer the Telerik UI for Blazor workflow article.

Prerequisites

To successfully complete the steps in this tutorial, make sure that you have installed a current Visual Studio version.
To learn more about the compatibility of the Telerik UI for Blazor components with different browser and .NET versions, see the system requirements.
This online documentation covers the latest version of Telerik UI for Blazor, which is 5.0.1. If needed, download the offline PDF documentation for the required older product version.

Step 0: Download Telerik UI for Blazor

If you have already purchased a Telerik UI for Blazor license, continue with the next step and create a new project.
If you are new to UI for Blazor and haven't purchased a license yet, you must download and install the trial version of the UI for Blazor components—this will activate your free trial and allow you to use the components. During the installation, select the Set up Telerik NuGet package source checkbox and the installer will configure the Telerik online NuGet feed automatically. You will use this feed later in the tutorial.

Trial users must complete the installation of the components. Otherwise their trial license will not be active and they cannot successfully complete the tutorial.

Step 1: Create a New Project

Open Visual Studio and select Create a new project.
Select the Blazor Web App project type, enter a name for your project, and then click Next.
Select the .NET 8 framework, the desired interactive render mode and interactivity location (per page or global).
Click Create.

Step 2: Add the Telerik NuGet Feed to Visual Studio

In this tutorial, you will use the Telerik NuGet feed to download the UI for Blazor components. This NuGet feed is private and requires you to authenticate with your Telerik user name and password:

In Visual Studio and go to Tools > NuGet Package Manager > Package Manager Settings.
Select Package Sources and then click the + button to add a new package source.
Enter a Name for the new package source, for example, telerik.com.
Add the https://nuget.telerik.com/v3/index.json URL as a Source. Click OK.

For alternative download options, check the Workflow article.

Step 3: Install the Telerik UI for Blazor Components

Right-click the Blazor Server project in the solution and select Manage NuGet Packages.
Install the Telerik Blazor NuGet package:
1. Select the telerik.com Package source that you added earlier. As this is a private NuGet feed, you must authenticate with your Telerik account username and password.
2. Select the Browse tab, find the NuGet package, and click Install. Commercial license holders must install Telerik.UI.for.Blazor. Trial users must install Telerik.UI.for.Blazor.Trial.

Step 4: Enable the Blazor UI Components

To enable the Telerik UI for Blazor components, you must add several client-side dependencies to the application, include the required @using statements, add the TelerikRootComponent component, and register the Telerik Blazor service.

4.1. Add the Telerik UI for Blazor Client Assets

1. Add the telerik-blazor.js file to your App.razor file as a static asset or from a CDN.

HTML

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

2. To select the appearance and color scheme for the Telerik Blazor components, add the theme stylesheet in your App.razor file. Reference it as a static asset or from a CDN.

HTML

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

3. (Optional) To enable the use of static assets in your project, add the app.UseStaticFiles(); line to the Program.cs of your Blazor Server project (by default, this line is already present). This step is required only if your application uses static assets.

var app = builder.Build();

// ...

//To enable static files from a package, make sure this is present.
app.UseStaticFiles();

// ...

app.Run();

4.2. Include @using Statements

In the ~/_Imports.razor file, add the @using directives below. This configures the project to recognize the Telerik components in all files. You can register one or both icon namespaces, depending on the icon type you use.

_Imports.razor

@using Telerik.Blazor
@using Telerik.Blazor.Components
@using Telerik.FontIcons
@using Telerik.SvgIcons

4.3. Add the TelerikRootComponent

Add a TelerikRootComponent component as a top-level component in the app and make sure it wraps all content. Add the component in the preferred layout file, for example, the MainLayout.razor or a custom layout file. The TelerikRootComponent must be placed in a layout page with enabled interactive mode, for example, MainLayout.razor.

.NET 8.0 introduces new render modes for the Blazor components. At the time of writing, the default render mode is static and not interactive, so you need to make this change explicitly in your app.

How you add the TelerikRootComponent to the app depends on which of the following approaches for configuring the render mode you chose:

Configure the Render Mode of the Entire App
Configure the Render Mode per Page

Configure the Render Mode of the Entire App

You can set the render mode for the entire app as suggested in the Blazor documentation. This will spare the need to set the render mode in every page and component.

<!DOCTYPE html>
<html lang="en">

<head>
    @* ... *@

    <HeadOutlet @rendermode="RenderMode.InteractiveServer" />
</head>

<body>
    <Routes @rendermode="RenderMode.InteractiveServer" />
    @* ... *@
</body>

</html>

@inherits LayoutComponentBase

<TelerikRootComponent>

    <div class="page">
        <div class="sidebar">
            <NavMenu />
        </div>
        <main>
            <div class="top-row px-4">
                <a href="https://learn.microsoft.com/aspnet/core/" target="_blank">About</a>
            </div>

            <article class="content px-4">
                @Body
            </article>
        </main>
    </div>

</TelerikRootComponent>

<div id="blazor-error-ui">
    An unhandled error has occurred.
    <a href="" class="reload">Reload</a>
    <a class="dismiss">🗙</a>
</div>

@page "/"

@* Telerik UI for Blazor components here *@

Configure the Render Mode per Page

As an alternative to setting the render mode for the entire app, you can set it only for specific pages and components. This is useful if you want to have different render modes in the app. In this case, make sure that the TelerikRootComponent is part of a component hierarchy that has interactive render mode.

See the example below - the TelerikRootComponent must wrap all the content in the viewport, so the whole <div class="page"> is moved from the MainLayout.razor to the TelerikLayout.razor.

@inherits LayoutComponentBase

@implements IDisposable

@Body

@code {
    protected override Task OnInitializedAsync()
    {
        return base.OnInitializedAsync();
    }

    public void Dispose()
    {
    }
}

@rendermode RenderMode.InteractiveServer

<TelerikRootComponent>

    <div class="page">
        <div class="sidebar">
            <NavMenu />
        </div>

        <main>
            <div class="top-row px-4">
                <a href="https://learn.microsoft.com/aspnet/core/" target="_blank">About</a>
            </div>

            <article class="content px-4">
                @ChildContent
            </article>
        </main>
    </div>

    <div id="blazor-error-ui">
        An unhandled error has occurred.
        <a href="" class="reload">Reload</a>
        <a class="dismiss">🗙</a>
    </div>

</TelerikRootComponent>

@code{
    [Parameter]
    public RenderFragment ChildContent {get;set;}
}

@page "/"

@rendermode RenderMode.InteractiveServer

<TelerikLayout>
    @* <TelerikLayout> must be recognized as a Razor component. *@
    @* You may need a @using statement in this file or in _Imports.razor. *@

    @* Telerik UI for Blazor components here *@

</TelerikLayout>

4.4. Register the Telerik Blazor Service

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.

// ...

var builder = WebApplication.CreateBuilder(args);

// ...

builder.Services.AddTelerikBlazor();

// ...

var app = builder.Build();

Now your Blazor Server project can use the Telerik UI for Blazor components.

Step 5: Add a Component to a View

The final step in this tutorial is to use a Telerik UI for Blazor component in a view and run it in the browser.

In the ~/Components/Pages/Home.razor view, add a TelerikButton component.

RAZOR
```
<TelerikButton>Say Hello</TelerikButton>
```

Optionally, hook up a click handler that will show a message. The resulting view will look like this:

RAZOR

@page "/"

<TelerikButton OnClick="@SayHelloHandler" ThemeColor="primary">Say Hello</TelerikButton>

<br />

@helloString

@code {
   MarkupString helloString;

   void SayHelloHandler()
   {
       string msg = string.Format("Hello from <strong>Telerik Blazor</strong> at {0}.<br /> Now you can use C# to write front-end!", DateTime.Now);
       helloString = new MarkupString(msg);
   }
}

Run the app in the browser by pressing F5. You should see something like this:

Well done! Now you have your first Telerik UI for Blazor component running in your Blazor Web App.

First Steps with UI for Blazor in a Web App

Prerequisites

Step 0: Download Telerik UI for Blazor

Step 1: Create a New Project

Step 2: Add the Telerik NuGet Feed to Visual Studio

Step 3: Install the Telerik UI for Blazor Components

Step 4: Enable the Blazor UI Components

4.1. Add the Telerik UI for Blazor Client Assets

4.2. Include @using Statements

4.3. Add the TelerikRootComponent

Configure the Render Mode of the Entire App

Configure the Render Mode per Page

4.4. Register the Telerik Blazor Service

Step 5: Add a Component to a View

Getting Started

Community

Support Resources

Sample Applications

Product Bundles

DevCraft

Web

Mobile

Document Management

Desktop

Reporting & Mocking

Automated Testing

CMS

UI/UX Tools

Debugging

Extended Reality

Free Tools

Support and Learning

Docs & Resources

Productivity and Design Tools

Configure the Render Mode of the Entire App

Configure the Render Mode per Page

Getting Started

Community

Support Resources

Sample Applications