CascadingValueProvider

The Values parameter accepts any collection of BitCascadingValue items, and every item becomes a CascadingValue component wrapped around the child content, in the order they are listed. Thanks to the implicit conversions of BitCascadingValue, a value can be written as the bare value itself (cascaded by its type) or as a (value, name) tuple (cascaded by that name), so neither nesting nor explicit type arguments are needed. The consumer below reads all five of them with plain [CascadingParameter] properties.

Cascading values are live: rebuilding the Values collection from the current state on each render pushes the new values down to every consumer automatically, exactly like a hand-written CascadingValue would. Only the consumers of a value that actually changed are re-rendered, so a set of unrelated values can share one provider. Play with the controls below and watch the consumer update:

The ValueList parameter takes a BitCascadingValueList, whose generic Add<T> method captures the static type of each value. That makes it the right choice for null values and nullable value types, which carry no usable runtime type of their own, and it adds one method per kind of entry - AddFixed<T>, AddIf<T>, AddLazy<T>, AddComputed<T> and AddObserved<T> - as well as Find<T>, Contains<T>, Remove<T> and Set<T> for a list that is kept around and revised. Setting both parameters is allowed: the ValueList items are provided first and the Values items after them, so Values wins on a conflict, which is what makes the pair a natural defaults-plus-overrides split.

Providers nest and shadow like any other cascading value: an inner provider overrides only the types and names it redefines, and everything else keeps flowing down from the outer one. The same rule applies inside a single provider, where a later value shadows an earlier one of the same type or name, so a set of defaults can be spread first and then selectively overridden. A shadowed value is dropped from the rendered chain instead of being cascaded and then hidden, so overriding costs nothing at render time.

Every value is cascaded as its ValueType, which is what decides the TValue of the generated CascadingValue and therefore which cascading parameters it can reach. It defaults to the runtime type of the value, so a null value has none of its own and the constructor throws unless a type is passed explicitly. Use new BitCascadingValue(value, typeof(T)), or the BitCascadingValue.From<T> factory that reads the static type of its argument, to cascade a value as a nullable type, a base type or an interface. Cascading a null under the same ValueType is also how an outer value is deliberately cleared for a subtree, which is what the inner provider below does to the [CascadingParameter] int? Count of the consumer:

Outer provider cascades 5 as int?: 5

Inner provider cascades null as the same int?: null

IsFixed tells Blazor that a value never changes, so its consumers are not subscribed for change notifications. That removes the per-consumer subscription bookkeeping and is the recommended setting for services, state containers and other values that are created once and only mutated in place. Use the BitCascadingValue.Fixed<T> factory, or the AddFixed<T> method of the list, as its shorthand. The flag can still be toggled later: the provider re-creates the underlying CascadingValue rather than letting the framework reject the change, and it does the same for a value that is renamed, so the consumers below it are created again and matched against the new name.

Setting Enabled to false on a value drops it from the rendered chain as if it had never been added, which is how a cascading value is provided conditionally without rebuilding the collection or wrapping the markup in an @if block. A disabled value also stops shadowing, so any outer provider or root level cascading value of the same type or name shows through again. Toggle the switches and watch the consumer fall back to null:

A BitCascadingValue that is held onto is observable: assigning its Value, Name, IsFixed or Enabled raises its Changed event, the provider re-renders itself in response, and the consumers see the new value even though the component that owns the values never re-rendered. For an object that is cascaded once and then mutated in place there is nothing to assign, so NotifyChanged() raises the same event on demand, and NotifyChangedAsync() is its awaitable form - the counterpart of CascadingValueSource.NotifyChangedAsync - which completes only once every provider listening to the value has re-rendered. The button below starts a background job that uses both, off the UI thread and without a single call to StateHasChanged on this page:

A value that already reports its own mutations does not need to be notified about by hand. Turning AutoNotify on, with the BitCascadingValue.Observed<T> factory or the AddObserved<T> method of the list, makes the cascading value watch the cascaded object itself: an INotifyPropertyChanged value is watched for its property changes and an INotifyCollectionChanged one (an ObservableCollection<T>, typically) for its collection changes, and each of them raises Changed on its own. The subscription only lives while a provider is listening, so a long lived state object never keeps a torn down page alive. The job below mutates the status object from a background thread and never calls NotifyChanged at all:

BitCascadingValue.Lazy<T>, and the AddLazy<T> method of the list, take a factory instead of a value and run it at most once, the first time the value is actually needed. A value that is disabled, that a later value of the same type and name shadows, or that belongs to a provider which is never rendered therefore costs nothing to build, and IsValueCreated reports whether the factory has run yet. The two values below share the same factory; the counter is read inside the provider, after the factories of that render have run, and the second one only shows up once the toggle enables it:

Factory invocations so far: 1

BitCascadingValue.Computed<T>, and the AddComputed<T> method of the list, also take a factory, but they run it every time the value is provided rather than once. That is what lets a single collection be built once, in a field or in the constructor, and still track the state its values are derived from, instead of being rebuilt from scratch on every render the way the Values example does it. It is also how one value is cascaded a second time under another type or name: a computed value that reads another one's Value stays in step with it, since both are read again on the same render. The collection below never changes; only what its two factories read does: