ValueStreamBuilder<M, T> constructor

const ValueStreamBuilder<M, T>({
  1. Key? key,
  2. required ValueStream<M> stream,
  3. T? distinctBy(
    1. M event
    )?,
  4. required ValueStreamWidgetBuilder<M> builder,
  5. ValueStreamBuilderCondition<M, T>? buildWhen,
  6. Widget? child,
  7. bool isReplayValueStream = true,
})

ValueStreamBuilder handles building a widget in response to new value. ValueStreamBuilder is analogous to StreamBuilder but has simplified API to reduce the amount of boilerplate code needed as well as ValueStream-specific performance improvements.

ValueStreamBuilder requires stream.hasValue to always be true, and the stream does not emit any error events. See ValueStreamHasNoValueError and UnhandledStreamError for more information.

Please refer to ValueStreamListener if you want to "do" anything in response to value changes such as navigation, showing a dialog, etc...

ValueStreamBuilder handles building a widget in response to new value. ValueStreamBuilder is analogous to StreamBuilder but has simplified API to reduce the amount of boilerplate code needed as well as ValueStream-specific performance improvements.

Example

ValueStreamBuilder<T>(
  stream: valueStream,
  builder: (context, value, child) {
    // return widget here based on valueStream's value
  },
  child: const SizedBox(), // Optional child widget that remains stable
);

An optional buildWhen can be implemented for more granular control over how often ValueStreamBuilder rebuilds.

  • buildWhen should only be used for performance optimizations as it provides no security about the value passed to the builder function.
  • buildWhen will be invoked on each stream value change.
  • buildWhen takes the previous value and current value and must return a bool which determines whether or not the builder function will be invoked.
  • The previous value will be initialized to the value of the stream when the ValueStreamBuilder is initialized.

buildWhen is optional and if omitted, it will default to true.

child is optional but is good practice to use if part of the widget subtree does not depend on the value of the stream.

Example

ValueStreamBuilder<T>(
  stream: valueStream,
  buildWhen: (previous, current) {
    // return true/false to determine whether or not
    // to rebuild the widget with valueStream's value
  },
  builder: (context, value, child) {
    // return widget here based on valueStream's value
  },
  child: const SizedBox(), // Optional child widget that remains stable
)

Implementation

const ValueStreamBuilder({
  super.key,
  required this.stream,
  this.distinctBy,
  required this.builder,
  this.buildWhen,
  this.child,
  this.isReplayValueStream = true,
});