Cascading Parameters

Analogy categoryAnalogies

Why Cascading Parameters Exist

Cascading parameters solve the 'prop drilling' problem where a value like the current theme or authenticated user needs to reach a component nested many levels deep, but every intermediate component would otherwise need to declare and forward a parameter it doesn't actually use itself; a <CascadingValue Value="@currentTheme"> wrapper in an ancestor component makes that value implicitly available to any descendant that declares a matching [CascadingParameter] property, regardless of how deeply nested it is.

🏏

Cricket analogy: A stadium-wide PA announcement about a rain delay reaches every player, umpire, and vendor simultaneously without someone physically relaying the message person to person, similar to how a CascadingValue reaches deeply nested descendants without intermediate components forwarding it.

Declaring CascadingValue and Consuming It

The provider wraps markup with <CascadingValue Value="@someObject" Name="Theme">...</CascadingValue>, optionally using Name to disambiguate when multiple cascading values of the same type exist in the tree; a consumer declares [CascadingParameter] public ThemeInfo Theme { get; set; } (matching by type, or by Name if specified), and Blazor automatically re-renders every consumer whenever the provided value changes, since CascadingValue treats the value as part of the render tree rather than a one-time snapshot.

🏏

Cricket analogy: A broadcaster labels multiple simultaneous camera feeds — 'Stump Cam', 'Drone Cam' — so the director can pull the exact one needed, similar to how CascadingValue's Name parameter disambiguates between multiple cascading values of the same type.

Common Uses and Performance Considerations

Cascading parameters are commonly used for cross-cutting concerns like the current authenticated user (AuthenticationStateProvider uses this internally), UI theming, or a shared EditContext within an EditForm, since these are genuinely needed by many unrelated descendants; however, because any change to a cascading value triggers a re-render of every consumer regardless of whether that specific value changed for them, overusing cascading parameters for frequently-changing data can cause unnecessary re-renders across large parts of the UI, so they should be reserved for relatively stable, broadly-needed state rather than per-item data.

🏏

Cricket analogy: Broadcasting a stadium-wide weather alert makes sense since every player and fan needs it, but constantly pinging every fan's phone with each individual ball's speed would be excessive, similar to reserving cascading values for stable, broadly-needed state rather than frequently-changing per-item data.

razor

@* App.razor or a top-level layout *@
<CascadingValue Value="@currentTheme" Name="Theme">
    <CascadingValue Value="@currentUser">
        <Router AppAssembly="typeof(Program).Assembly">
            <!-- routed content nested arbitrarily deep -->
        </Router>
    </CascadingValue>
</CascadingValue>

@code {
    private ThemeInfo currentTheme = new("dark");
    private UserInfo currentUser = new("jane.doe");
}

@* Deeply nested descendant, e.g. NavBadge.razor *@
@code {
    [CascadingParameter(Name = "Theme")]
    public ThemeInfo? Theme { get; set; }

    [CascadingParameter]
    public UserInfo? CurrentUser { get; set; }
}

Blazor's own <AuthorizeView> and CascadingAuthenticationState build on this exact mechanism internally — the authenticated user's ClaimsPrincipal is supplied once near the app's root via CascadingValue and consumed by any component, at any depth, via [CascadingParameter].

Every descendant that declares a matching [CascadingParameter] re-renders whenever the cascaded value changes, even if that particular descendant doesn't visually depend on the changed part of the value. For large component trees, prefer immutable or rarely-changing objects as cascading values, and consider splitting frequently-changing data into narrower, separately cascaded values.

CascadingValue lets an ancestor component implicitly supply data to any descendant, at any nesting depth.
Descendants opt in with [CascadingParameter], matched by type or by an explicit Name.
This avoids prop drilling, where every intermediate component would otherwise forward an unused parameter.
Name disambiguates multiple cascading values of the same type flowing through the same tree.
Blazor's built-in AuthorizeView and authentication state use CascadingValue internally.
Every consumer re-renders whenever the cascaded value changes, which can hurt performance if overused for volatile data.
Reserve cascading parameters for broadly-needed, relatively stable state like theme, user, or EditContext.