Cascading parameter

✅ Similar to Blazor Server

Cascading parameter is a feature of Blazor that allows components to share data with their descendants without the need for explicit props or state management.

• Passing a parameter using CascadingParameter.
• Passing multiple parameters using CascadingParameter.
• Common mistake.
• Detect changes.

You can download the example code used in this topic on GitHub.

Passing a parameter using CascadingParameter

To pass a parameter from an ancestor component to descendant components, follow these steps:

1. In your ancestor component, declare a public property in the code section. This public property should contain the data you wish to pass to the descendant components.

@code {
    public string Data { get; set; } = "Data from grand parent component.";
}

2. Wrap the descendant components with the CascadingValue component.

<CascadingValue Value="Data">
    <Parent />
</CascadingValue>

3. In your descendant component, declare a property with the same type as the one in the ancestor component (e.g., string), and use the CascadingParameter attribute in the code section. This will allow the descendant component to receive the data from the ancestor component via the CascadingValue component.

@code {
    [CascadingParameter]
    public string ReceivedValue { get; set; } = "";
}

Passing multiple parameters using CascadingParameter

Blazor also allows for the passing of multiple parameters from an ancestor component to descendant components using CascadingParameter. To do this:

1. Declare properties in the ancestor component's code section.

@code {
    public string Data1 { get; set; } = "First data.";
    public string Data2 { get; set; } = "Second data.";
}

2. Nest multiple CascadingValue components, in any order, to pass data. When passing multiple parameters, the type is not considered as a factor to differentiate them, instead, name each passing parameter. By default, the passing parameter name is the name of the property in the ancestor component. However, you can rename your passing parameter by using the Name parameter in the CascadingValue component.

<CascadingValue Value="Data1">
    <CascadingValue Value="Data2" Name="CascadeParam2">
        <Parent />
    </CascadingValue>
</CascadingValue>

In the code sample, the Data1 is a cascading parameter with the name Data1 and Data2 is a cascading parameter with the name CascadeParam2. We will use Data1 and CascadeParam2 in the descendant components to catch the parameter.

3. In your descendant component, declare properties and use the CascadingParameter attribute in the code section.

@code {
    [CascadingParameter]
    public string Data1 { get; set; } = "";

    [CascadingParameter(Name = "CascadeParam2")]
    public string ReceivedValue2AtParent { get; set; } = "";
}

Common mistake

When utilizing the Cascading Parameter approach, it is important to not alter the reference of a passed parameter in any descendant component. The following code in a descendant component demonstrates this error:

@code {
    [CascadingParameter]
    public ExampleClass ReceivedValueAtParent { get; set; } = new();

    public void Correct()
    {
        ReceivedValueAtParent.Data = "Value changed";
    }

    public void Mistake()
    {
        ReceivedValueAtParent = new()
        {
            Data = "Reference changed"
        };
    }
}

What happens when you change the reference of a passed parameter?

The altered value only impacts the descendant component and not any other descendant or ancestor component, as the following video illustrates:

Detect changes

In this section, you will learn how to detect and handle changes made to the passed parameter value in both the ancestor component and descendant components. Specifically, you will learn how to:

• Detect changes from the ancestor component
• Detect changes from the descendant components

Detect changes from the ancestor component

Anytime the ancestor component updates the value of a cascading parameter, the descendant components will be re-rendered automatically. You can also listen for these changes by overriding the OnParametersSet() method in your descendant component. For more information, refer to the Component Lifecycle tutorial.

Detect changes from the descendant components

Whenever a descendant component updates the value of a cascading parameter, the ancestor component will not be automatically re-rendered, unlike changes made from the ancestor component. To make the ancestor component respond to changes made in the descendant component, you need to notify the ancestor component whenever you make a change.

1. In your ancestor component, declare a notify method in the code section.

@code {
    ...
    public void NotifyChange()
    {
        InvokeAsync(StateHasChanged);
    }
}

2. Pass this to the descendant components.

<CascadingValue Value="this">
    <CascadingValue Value="ExampleInstance">
        <Parent />
    </CascadingValue>
</CascadingValue>

3. In your descendant components, whenever you make a change to the cascading parameter, call the notify method of the ancestor component to notify the ancestor component of the change.

@code {
    [CascadingParameter]
    public ExampleClass ReceivedValueAtParent { get; set; } = new();

    [CascadingParameter]
    public GrandParent? Ancestor { get; set; }

    public void UpdateValue()
    {
        ReceivedValueAtParent.Data = "Value changed at parent";
        Ancestor?.NotifyChange();
    }
}