diff --git a/components/rootcomponent/overview.md b/components/rootcomponent/overview.md index 1ba3f0422..b5417efd9 100644 --- a/components/rootcomponent/overview.md +++ b/components/rootcomponent/overview.md @@ -23,7 +23,7 @@ The `TelerikRootComponent` is responsible for the following tasks: * There is no risk for the popups to be trapped by scrollable containers, or clipped by containers with an `overflow:hidden` style. * It exposes the `DialogFactory` for using [predefined dialogs]({%slug dialog-predefined%}). -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. +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, otherwise an [exception may occur]({%slug common-kb-component-requires-telerikrootcomponent%}). 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. ## Using TelerikRootComponent @@ -82,3 +82,4 @@ If you are using Telerik components in a Blazor app with **Per page/component** * [Popup Troubleshooting]({%slug troubleshooting-general-issues%}) * [Setting up Telerik Blazor apps]({%slug getting-started/what-you-need%}) +* [Exception: Telerik component requires a TelerikRootComponent]({%slug common-kb-component-requires-telerikrootcomponent%}) diff --git a/getting-started/what-you-need.md b/getting-started/what-you-need.md index aeccadecc..e5d532b6f 100644 --- a/getting-started/what-you-need.md +++ b/getting-started/what-you-need.md @@ -222,7 +222,7 @@ The `TelerikRootComponent` placement depends on the interactivity location of th > * .NET 8 Blazor Web Apps with **Global** interactivity location > * Blazor Server, WebAssembly and Hybrid apps in all .NET versions > -> If you have a .NET 8 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 layout file. Refer to section [Interactivity Considerations]({%slug rootcomponent-overview%}#interactivity-considerations) and article [Using TelerikRootComponent with Per Page/Component Interactivity]({%slug rootcomponent-percomponent%}). +> If you have a .NET 8 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 component will not detect it]({%slug common-kb-component-requires-telerikrootcomponent%}). Refer to section [Interactivity Considerations]({%slug rootcomponent-overview%}#interactivity-considerations) and article [Using TelerikRootComponent with Per Page/Component Interactivity]({%slug rootcomponent-percomponent%}). ### Optimal TelerikRootComponent Usage diff --git a/knowledge-base/common-component-requires-telerikrootcomponent.md b/knowledge-base/common-component-requires-telerikrootcomponent.md new file mode 100644 index 000000000..a2175f231 --- /dev/null +++ b/knowledge-base/common-component-requires-telerikrootcomponent.md @@ -0,0 +1,61 @@ +--- +title: Telerik Component Requires a TelerikRootComponent +description: Learn how to fix the exception А Telerik component on the requested view requires a TelerikRootComponent in MainLayout or a parent component. +type: troubleshooting +page_title: Telerik Component Requires a TelerikRootComponent +slug: common-kb-component-requires-telerikrootcomponent +tags: telerik, blazor, rootcomponent +ticketid: +res_type: kb +--- + +## Environment + + + + + + + + +
ProductUI for Blazor
TelerikRootComponent for Blazor
+ + +## Description + +This knowledge base article explains how to avoid or fix the exception about a missing `TelerikRootComponent`. + + +## Error Message + +>warning Exception: A Telerik component on the requested view requires a TelerikRootComponent in MainLayout or a parent component. + + +## Cause + +The error occurs when a Telerik Blazor component cannot detect a `TelerikRootComponent` instance as a parent or ancestor in the Blazor component tree. Normally, each Telerik Blazor component obtains a reference to the `TelerikRootComponent` from a [cascading value](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/cascading-values-and-parameters), which the `TelerikRootComponent` sets. + +More specifically, the exception implies the following issues with the application setup: + +* A Blazor application is missing a `TelerikRootComponent` in `MainLayout.razor` or any other layout file that is currently in use. +* A [.NET 8 Blazor Web App](https://learn.microsoft.com/en-us/aspnet/core/blazor/project-structure?view=aspnetcore-8.0#blazor-web-app) has a `TelerikRootComponent` in a used layout file, but the app's **Interactivity location** is set to **Per page/component**. In such cases, the layout files use static render mode and the `TelerikRootComponent` is unable to pass cascading values down the component tree. + + +## Solution + +To fix and avoid the `TelerikRootComponent` exception: + +* [Add a `TelerikRootComponent` to one or more layout files]({%slug getting-started/what-you-need%}#telerikrootcomponent), depending on the application's layout structure. +* When using the .NET 8 Blazor Web App project template, [create the app with a **Global** interactivity location](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#apply-a-render-mode-to-the-entire-app). +* If your scenario requires a **Per page/component** interactivity location, place the `TelerikRootComponent` in an interactive Razor component. Refer to [Using `TelerikRootComponent` with Per Component Interactivity]({%slug rootcomponent-percomponent%}). + +> To avoid [problems with popup positioning]({%slug troubleshooting-general-issues%}#wrong-popup-position), wrap all the web page content in a `TelerikRootComponent`. +> +> Do not nest multiple `TelerikRootComponent` instances. + + +## See Also + +* [`TelerikRootComponent` Purpose and Overview]({%slug rootcomponent-overview%}) +* [Typical Usage of the `TelerikRootComponent`]({%slug getting-started/what-you-need%}#telerikrootcomponent) +* [Using `TelerikRootComponent` with Per Component Interactivity]({%slug rootcomponent-percomponent%}) diff --git a/troubleshooting/general-issues.md b/troubleshooting/general-issues.md index 29312641e..63da5089b 100644 --- a/troubleshooting/general-issues.md +++ b/troubleshooting/general-issues.md @@ -12,36 +12,25 @@ position: 1 This page provides solutions for common issues you may encounter while working with Telerik UI for Blazor components. -* [TelerikRootComponent is missing in .NET 8.0](#telerikrootcomponent-is-missing-in-net-80) -* [Popups Do Not Work](#popups-do-not-work) -* [Wrong Popup Position](#wrong-popup-position) +* [TelerikRootComponent is missing]({%slug common-kb-component-requires-telerikrootcomponent%}) +* [Popups do not work](#popups-do-not-work) +* [Wrong popup position](#wrong-popup-position) * [Unable to find package Telerik.Documents.SpreadsheetStreaming](#unable-to-find-package-telerikdocumentsspreadsheetstreaming) * [Cannot provide a value for property 'Localizer'](#cannot-provide-a-value-for-property-localizer) * [Slow Performance](#slow-performance) -* [JavaScript Errors]({%slug troubleshooting-js-errors%}) -* [Issues After Deployment]({%slug deployment-troubleshooting%}) +* [JavaScript errors]({%slug troubleshooting-js-errors%}) +* [Issues after deployment]({%slug deployment-troubleshooting%}) * [Content Security Policy]({%slug troubleshooting-csp%}) -* [NuGet Feed Troubleshooting]({%slug troubleshooting-nuget%}) -* [Upload Troubleshooting]({%slug upload-troubleshooting%}) +* [NuGet feed troubleshooting]({%slug troubleshooting-nuget%}) +* [Upload troubleshooting]({%slug upload-troubleshooting%}) -## TelerikRootComponent is missing in .NET 8.0 - -Using a [Blazor Web App template](https://learn.microsoft.com/en-us/aspnet/core/blazor/project-structure?view=aspnetcore-8.0#blazor-web-app), the following error occurs: - ->warning Error: System.Exception: A Telerik component on the requested view requires a TelerikRootComponent to be added to the root of the MainLayout component of the app. - -The root cause for this is a difference in the required configuration when using [interactive render modes](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#enable-support-for-interactive-render-modes). - -This error will be thrown if the [`TelerikRootComponent`]({%slug rootcomponent-overview%}) is placed in a layout page that does not have interactive mode enabled. - -The `TelerikRootComponent` must be placed in a layout page (e.g. `MainLayout.razor`) with enabled interactive mode. Read more in [Web App - Add TelerikRootComponent]({%slug getting-started/web-app%}#43-add-the-telerikrootcomponent). ## Popups Do Not Work There are three common reasons for this -* Missing [``]({%slug getting-started/what-you-need%}#configuring-the-project) from the app. -* [Missing JS Interop file]({%slug troubleshooting-js-errors%}#microsoftjsinteropjsexception-could-not-find-) -* Special positioning on the `` element. +* Missing [``]({%slug getting-started/what-you-need%}#telerikrootcomponent) from the app. +* [Missing `telerik-blazor.js` file]({%slug troubleshooting-js-errors%}#telerikblazor-was-undefined) +* Special positioning on the `` element or any other parent of the `TelerikRootComponent`. The `` element is the topmost component that a developer can access in Blazor. This means that we cannot place our popups higher than that in the DOM. Thus, their position and visibility depend on the position of the `` element matching the position of the `` element.