skip to content

In a Blazor Web App, how does [CascadingParameter] find a CascadingValue, and when would you use IsFixed or AddCascadingValue instead of the component?

level: seniorimportance: should knowfreq 36%

answer

  1. matched by type, or by Name
  2. the closest ancestor wins
  3. subscribers re-render on change
  4. IsFixed cannot change dynamically
  5. AddCascadingValue and CascadingValueSource<T>

basics

~20 s

A [CascadingParameter] property receives the value from the closest ancestor CascadingValue of a matching type, or with a matching Name. IsFixed="true" skips change tracking for values that never change; AddCascadingValue registers a root-level value through DI that also reaches interactive components across render mode boundaries.

solid answer

~40 s

`<CascadingValue Value="currentDepot">` makes `currentDepot` available to every descendant; a descendant receives it with `[CascadingParameter] public Depot? Depot { get; set; }`. Matching is by **type**, closest ancestor first, unless both sides use a `Name`, in which case the name must match. By default each receiving component **subscribes**: when the parent re-renders with a new value, every subscriber re-renders too. `IsFixed="true"` says the value will never change, so Blazor creates no subscriptions - cheaper for large trees - and changing `IsFixed` after the first render throws. Since .NET 8, `builder.Services.AddCascadingValue(...)` registers a **root-level** cascading value through DI; with a `CascadingValueSource<T>` you can push updates with `NotifyChangedAsync`. Root-level values matter in Blazor Web Apps because a `<CascadingValue>` placed in a static layout does not flow across a render mode boundary into interactive components.

code

csharp · 7 lines
csharp
builder.Services.AddCascadingValue(sp => new FleetTheme { Dense = true });

builder.Services.AddCascadingValue(sp =>
{
    var depot = new Depot("North");
    return new CascadingValueSource<Depot>(depot, isFixed: false);
});

go deeper

for a junior

Know that CascadingValue shares a value with all descendants and that they receive it with [CascadingParameter].

for a middle

Explain matching by type versus Name, closest-ancestor resolution, subscriber re-renders and what IsFixed changes.

for a senior

Diagnose missing cascaded values across render mode boundaries, move them to AddCascadingValue or CascadingValueSource<T>, and use IsFixed to stop large trees re-rendering.

for a principal

Govern what a component library cascades: a short list of root-level values with clear owners, parameters for local data, and services for mutable shared state.

## The mechanism A **cascading value** is data an ancestor makes available to all its descendants without passing it through every intermediate component's parameters. Blazor implements it with two pieces: - the `CascadingValue<TValue>` component, with parameters `Value`, `Name`, `IsFixed` and `ChildContent`; - the `[CascadingParameter]` attribute on a property in a descendant, with an optional `Name`. In a fleet-maintenance app, a page might wrap its content in `<CascadingValue Value="selectedDepot">` so the vehicle list, the work-order grid and a summary panel all know which depot is selected. ## How a descendant finds the value 1. Blazor walks **up** the component tree from the receiving component. 2. Without a `Name`, the first supplier whose value type is assignable to the property type wins - so the **closest ancestor** of a matching type shadows any further up. 3. With `[CascadingParameter(Name = "DepotId")]`, only a supplier with the same `Name` matches; names let you cascade two values of the same type (two `int`s, say) without ambiguity. 4. If nothing matches, the property keeps its default value - there is no error, so check for `null` where it matters. ## Change tracking and IsFixed By default the relationship is live. Each receiving component is registered as a **subscriber** of the `CascadingValue`. When the component that hosts `<CascadingValue>` re-renders and the value may have changed, every subscriber is told to re-render as well. That is convenient, and for a value consumed by hundreds of components (every row of a big grid, say) it is also a cost. `IsFixed="true"` declares that the value will not change for the lifetime of the `CascadingValue`: - Blazor does not track subscribers, so a re-render of the host does not fan out to the consumers; - receiving components still get the value once, when they are created; - changing `IsFixed` itself after the first render throws `InvalidOperationException` ("The value of IsFixed cannot be changed dynamically"). Use it for things like a theme object, a service-like helper or the app's configuration that is set once. ## Root-level cascading values Since .NET 8 a value can be cascaded from the **DI container** rather than from a component: | Registration | Behaviour | |---|---| | `AddCascadingValue(sp => new FleetTheme())` | a root-level value for the whole component hierarchy | | `AddCascadingValue("Region", sp => ...)` | the same, matched by name | | `AddCascadingValue(sp => new CascadingValueSource<Depot>(depot, isFixed: false))` | a value whose owner can later call `NotifyChangedAsync()` or `NotifyChangedAsync(newValue)` to update subscribers | | `TryAddCascadingValue(...)` | registers only if no value of that type is registered yet | Root-level values solve a Blazor Web App problem. **Cascading values do not cross render mode boundaries**: a `<CascadingValue>` in a statically rendered layout is not available to an interactive island below it, because the interactive component is recreated in another runtime and cascading values are not serialized. Root-level values are DI services, so each runtime resolves its own, and interactive components receive them. ## When not to cascade - For a value only one or two levels deep, a plain `[Parameter]` is clearer and easier to trace. - For state many unrelated components mutate, a scoped state container service is often simpler than cascading a mutable object. - Avoid cascading large mutable objects without `IsFixed`, since every host re-render can fan out to every consumer.

  • A <CascadingValue> in MainLayout works for static pages but is null in an InteractiveServer component. Why, and what fixes it?
    With per-page interactivity the layout renders statically, and the interactive component is recreated in its circuit across a render mode boundary. Cascading values are not serialized across that boundary, so the component sees nothing. Register the value as a root-level cascading value with `AddCascadingValue` in Program.cs, which each runtime resolves through DI, or make the whole app interactive so the layout and the component share one runtime.
  • How does a root-level cascading value notify components when it changes?
    Register it as a `CascadingValueSource<T>` created with `isFixed: false`, and keep a reference to that source. Calling `NotifyChangedAsync()` after mutating the value, or `NotifyChangedAsync(newValue)` to replace it, makes every subscribed component re-render with the current value. A source created with `isFixed: true` has no subscribers.

  • A [CascadingParameter] matches its supplier by property name, like a normal parameter.
  • If no ancestor supplies a cascading value, Blazor throws at render time.
  • IsFixed can be switched off later when the value finally needs to change.
  • A CascadingValue in a static layout reaches interactive components below it automatically.
  • Cascading values are copied once, so consumers never re-render when the value changes.

Assumes .NET 10; root-level cascading values (AddCascadingValue, CascadingValueSource<T>) and the render-mode boundary rule arrived with Blazor Web Apps in .NET 8.