|
| 1 | +--- |
| 2 | +title: Overview |
| 3 | +page_title: RootComponent - Overview |
| 4 | +description: Overview of the Telerik Root Component for Blazor. |
| 5 | +slug: rootcomponent-overview |
| 6 | +tags: telerik,blazor,telerikrootcomponent,rootcomponent |
| 7 | +published: True |
| 8 | +position: 0 |
| 9 | +--- |
| 10 | + |
| 11 | +# TelerikRootComponent Overview |
| 12 | + |
| 13 | +The `TelerikRootComponent` is a special component in Telerik UI for Blazor. Its placement and configuration will affect all its child Telerik Blazor components. This article describes the purpose and usage of `TelerikRootComponent`. |
| 14 | + |
| 15 | + |
| 16 | +## Purpose |
| 17 | + |
| 18 | +The `TelerikRootComponent` is responsible for the following tasks: |
| 19 | + |
| 20 | +* It provides settings to all its child Telerik components, for example about the [icon type]({%slug common-features-icons%}#set-global-icon-type) or [right-to-left (RTL) support]({%slug rtl-support%}). |
| 21 | +* It renders all Telerik popups, which has the following benefits: |
| 22 | + * It's more reliable that the popups will display on top of the other page content. |
| 23 | + * There is no risk for the popups to be trapped by scrollable containers, or clipped by containers with an `overflow:hidden` style. |
| 24 | +* It exposes the `DialogFactory` for using [predefined dialogs]({%slug dialog-predefined%}). |
| 25 | + |
| 26 | +The `TelerikRootComponent` achieves all these tasks with the help of [cascading values](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/cascading-values-and-parameters). That's why it is crucial for the root component to wrap all other Telerik components in the app. To ensure correct popup position, it is also highly recommended for the `TelerikRootComponent` to be the top-level component in the app and wrap all other content, including the application layout. |
| 27 | + |
| 28 | + |
| 29 | +## Using TelerikRootComponent |
| 30 | + |
| 31 | +The recommended way to add `TelerikRootComponent` to a Blazor app is to: |
| 32 | + |
| 33 | +1. Create a new layout file in the app, for example, `TelerikLayout.razor`. |
| 34 | +1. (optional) Place the new layout in the same folder as the default application layout (usually `MainLayout.razor`). |
| 35 | +1. Add a `<TelerikRootComponent>` tag to the new layout and set `@Body` as the root component's child content. |
| 36 | +1. Make the new layout a parent of the default application layout. |
| 37 | + |
| 38 | +The above approach has the following benefits: |
| 39 | + |
| 40 | +* There is a separation of concerns and the `TelerikRootComponent` can be a parent of multiple other layouts. |
| 41 | +* You can use `DialogFactory` (predefined Telerik dialogs) in `MainLayout.razor`. |
| 42 | + |
| 43 | +However, it is also possible to [add `<TelerikRootComponent>` directly to the existing application layout(s)](#adding-telerikrootcomponent-to-existing-layout). |
| 44 | + |
| 45 | +>caption Adding TelerikRootComponent to a new layout |
| 46 | +
|
| 47 | +<div class="skip-repl"></div> |
| 48 | + |
| 49 | +````TelerikLayout.razor |
| 50 | +@inherits LayoutComponentBase |
| 51 | +
|
| 52 | +<TelerikRootComponent> |
| 53 | + @Body |
| 54 | +</TelerikRootComponent> |
| 55 | +```` |
| 56 | +````MainLayout.razor |
| 57 | +@inherits LayoutComponentBase |
| 58 | +@layout TelerikLayout |
| 59 | +
|
| 60 | +@* The other MainLayout.razor content remains the same. *@ |
| 61 | +```` |
| 62 | + |
| 63 | +### Adding TelerikRootComponent to Existing Layout |
| 64 | + |
| 65 | +>caption Adding TelerikRootComponent to MainLayout.razor |
| 66 | +
|
| 67 | +<div class="skip-repl"></div> |
| 68 | + |
| 69 | +````CSHTML |
| 70 | +@inherits LayoutComponentBase |
| 71 | +
|
| 72 | +<TelerikRootComponent> |
| 73 | + @* All the MainLayout.razor content becomes nested in the Telerik root component. *@ |
| 74 | +</TelerikRootComponent> |
| 75 | +```` |
| 76 | + |
| 77 | + |
| 78 | +## .NET 8 Notes |
| 79 | + |
| 80 | +.NET 8 introduced the concept of static Blazor apps with optional interactive components. The following requirements and considerations apply to the `TelerikRootComponent`: |
| 81 | + |
| 82 | +* The `TelerikRootComponent` must reside in an interactive layout or component. |
| 83 | +* Application layouts are interactive only if the whole app is interactive. To achieve this, set *Interactivity location* of the app to *Global* during app creation. |
| 84 | +* When the whole app is interactive and the `TelerikRootComponent` is in an (interactive) layout file, the component provides cascading values to all other Telerik components in the app. |
| 85 | +* When the app is static and the `TelerikRootComponent` is in a (static) layout file, its cascading values cannot reach other Telerik components, because [cascading values cannot pass data across render mode boundaries](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/cascading-values-and-parameters?view=aspnetcore-8.0#cascading-valuesparameters-and-render-mode-boundaries). As a result, you need to add the `TelerikRootComponent` on each interactive page (component). Component interactivity is inherited. |
| 86 | +* When the `TelerikRootComponent` is added to a `.razor` file, you cannot reference the `DialogFactory` and use [predefined dialogs]({%slug dialog-predefined%}) in the same `.razor` file (but a [workaround exists](https://github.com/telerik/blazor-ui/tree/master/rootcomponent/BlazorWebAppServer)). The `DialogFactory` will be available to child components of the `TelerikRootComponent`. See section [Using TelerikRootComponent](#using-telerikrootcomponent) above for more information and examples. |
| 87 | + |
| 88 | +See the following resources for more details and examples of using Telerik Blazor components and `TelerikRootComponent` in .NET 8 apps. |
| 89 | + |
| 90 | +* [Interactivity Considerations]({%slug getting-started/web-app%}#interactivity-considerations) |
| 91 | +* [Adding `TelerikRootComponent` to Blazor Web App]({%slug getting-started/web-app%}#43-add-the-telerikrootcomponent) |
| 92 | +* [.NET 8 Blazor Web App sample project on GitHub](https://github.com/telerik/blazor-ui/tree/master/rootcomponent/BlazorWebAppServer) |
| 93 | + |
| 94 | + |
| 95 | +## TelerikRootComponent Parameters |
| 96 | + |
| 97 | +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) |
| 98 | + |
| 99 | +| Parameter | Type and Default Value | Description | |
| 100 | +| --- | --- | --- | |
| 101 | +| `EnableRtl` | `bool` | Enables [right-to-left (RTL) support]({%slug rtl-support%}). | |
| 102 | +| `IconType` | `IconType` enum <br /> (`Svg`) | The icon type, which other Telerik components will use to render internal icons. Regardless of this parameter value, you can use freely the [`<TelerikFontIcon>`]({%slug common-features-icons%}#fonticon-component) and [`<TelerikSvgIcon>`]({%slug common-features-icons%}#svgicon-component) components, and [set the `Icon` parameter of other Telerik components]({%slug button-icons%}) to any type that you wish. | |
| 103 | +| `Localizer` | `Telerik.Blazor.Services.ITelerikStringLocalizer` | The Telerik localization service. Normally, the [localizer should be defined as a service in `Program.cs`]({%slug globalization-localization%}). Use the `Localizer` parameter only in special cases when this is not possible. | |
| 104 | + |
| 105 | + |
| 106 | +## See Also |
| 107 | + |
| 108 | +* [Popup Troubleshooting]({%slug troubleshooting-general-issues%}) |
| 109 | +* [Setting up Telerik Blazor apps]({%slug getting-started/what-you-need%}) |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments