Cascading parameter

Cascading parameter is a technique that let you pass a parameter from an ancestor component to its descendant components. In this tutorial, you will discover:

• How to use CascadingParameter.
• Common mistake.
• Detect changes.

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

Passing a parameter using CascadingParameter

The following steps will help you to pass a parameter from an ancestor component to the descendant components.

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

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

2. Use the CascadingValue component to wrap the descendant components.

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

3. In your descendant component, declare a property with the same type from the ancestor component (string in this example) and use the CascadingParameter attribute in the code section.

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

Passing multiple parameters using CascadingParameter

In the above example, Blazor Server will recognize the parameter from the ancestor component and the descendant components by the type of the parameter. For example, you can pass a string, an int from the ancestor component to the descendant components. Sometimes, you want to pass multiple parameters, regardless of their types.

1. In your ancestor component, declare properties in the code section.

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

2. Use multiple nested CascadingValue components to pass data. The order is irrelevant. By passing multiple parameters, the type is not considered as a factor to differentiate parameters. Instead, you have to name each passing parameter. By default, the passing parameter name is the name of the property in the ancestor component. You can rename your passing parameter by using Name parameter in 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; } = "";
}

You don't need to specify the passing parameter name (Data1) when the name of the property matches with the passing parameter. When the passing parameter name (CascadeParam2) doesn't match the property name (ReceivedValue2AtParent) then you need to specify the parameter name in the attribute. For example: [CascadingParameter(Name = "CascadeParam2")].

Common mistake

When using the Cascading parameter technique, don't change the reference of a passed parameter in any descendant component. The following code in the descendant component illustrates this mistake:

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

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

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

What will happen if you change the reference of a passed parameter?

The changed value only affects in the descendant component and not in another descendant nor ancestor component as the following video illustrates:

Detect changes

You can change the passed parameter value in the ancestor component and the descendant components. In this section, you will learn:

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

Detect changes from the ancestor component

Anytime the ancestor component changes the value of a cascading parameter, the descendant components will be re-rendered. You can also listen to these changes by override the OnParametersSet() method of your descendant component. See Component Lifecycle tutorial.

Detect changes from the descendant components

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

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 made a change to the cascading parameter, call the notify method of the ancestor component.

@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();
    }
}