Cascading values by type

Previously we saw how to cascade a value by name. Setting a Name is important because it is used to push a value specified in a CascadingValue into the correct properties in consuming components by matching up their names. Another option is to specify a CascadingValue without specifying a Name, when Blazor encounters a cascading value specified in this way it will inject its value into a component's property if the property meets the following criteria.

Prerequisite: Cascading parameters work under all render modes (Static Server, InteractiveServer, InteractiveWebAssembly, and InteractiveAuto). However, components that react to value changes may require an interactive render mode. See Render modes for details.

1. The property is decorated with a CascadingParameterAttribute.
2. The [CascadingParameter] does not have a Name specified.
3. The property is of the same Type as set in the CascadingValue (e.g. boolean).
4. The property has a setter.

The property does not need to be public. We recommend marking it as private with a setter so it is clear the value comes from the render tree and not from application code.

For example, the following CascadingValue will match both CascadingParameter properties in SomeComponent.

<CascadingValue Value=@true>
  <SomeComponent/>
</CascadingValue>

Property1 = @Property1
Property2 = @Property2

@code
{
  [CascadingParameter]
  private bool Property1 { get; set; }

  [CascadingParameter]
  private bool Property2 { get; set; }
}

An unnamed CascadingValue is not as specific as a CascadingValue that has a Name specified, because every CascadingParameter decorated property with the correct type and no Name will consume the value. In cases where we define a simple .NET type such as a bool or an int it is recommended we use a named parameter, however, sometimes the type of the value is sufficient to identify its purpose; specifying a name would be redundant, and excluding it is therefore a small time saver.

As the recruitment application grows we might end up with multiple cascading parameters, such as:

• bool ViewAnonymizedData
  Indicates if personally-identifying information should be hidden.
• string DateFormat
  Consuming components can use this to format dates in a uniform manner.
• string LanguageCode
  Components could use this to display translated text.

The clear pattern emerging here is that these are all related to a user's preferences. Rather than having Razor mark-up with multiple CascadingValue elements, like this:

<CascadingValue Name="ViewAnonymizedData" Value=@ViewAnonymizedData>
  <CascadingValue Name="DateFormat" Value=@DateFormat>
    <CascadingValue Name="LanguageCode" Value=@LanguageCode>
      (Body goes here)
    </CascadingValue>
  </CascadingValue>
</CascadingValue>

It would make more sense (and take less code) to have a custom class:

public class UserPreferences
{
  public bool ViewAnonymizedData { get; set; }
  public string? DateFormat { get; set; }
  public string? LanguageCode { get; set; }
}

and then create your Razor mark-up like this:

<CascadingValue Value=@UserPreferences>
</CascadingValue>

Consuming components then only need a single property marked as a [CascadingParameter] rather than three.

@if (!UserPreferences.ViewAnonymizedData)
{
  <div>
    <span>Name</span> @Candidate.Name
  </div>
  <div>
    <span>Date of birth</span> @Candidate.DateOfBirth.ToString(UserPreferences.DateFormat)
  </div>
  <ViewAddress Address=@Candidate.Address/>
}
else
{
  <span>[Anonmymized view]</span>
}

@code
{
  [CascadingParameter]
  private UserPreferences? UserPreferences { get; set; }
}

Obviously, this example excludes how to translate the static text based on the UserPreferences.LanguageCode.

IsFixed and root-level registration

By default, Blazor re-renders every component between a CascadingValue and its consumers whenever the value changes. If we know the value will never change, we can set IsFixed="true" on the CascadingValue element to skip change tracking and improve render performance.

In .NET 8 and later, we can also register cascading values at the application root using AddCascadingValue:

builder.Services.AddCascadingValue(sp => new UserPreferences
{
  ViewAnonymizedData = false,
  DateFormat = "yyyy-MM-dd",
  LanguageCode = "en"
});

Root-level cascading values feed every component in the application, just as if they were wrapped in a CascadingValue element at the top of the render tree. The IsFixed option is available through the same registration:

builder.Services.AddCascadingValue(sp => new UserPreferences
{
  ViewAnonymizedData = false,
  DateFormat = "yyyy-MM-dd",
  LanguageCode = "en"
}, isFixed: true);

When using type-based resolution without a name, the nearest matching CascadingValue by type wins, whether registered at the root or in the render tree.