property #

An observable value holder. Update widgets without setState, rebuilding only the part of the tree that reads the value.

A Property is a ValueListenable, so it works with PropertyBuilder and with everything the framework already has — ValueListenableBuilder, ListenableBuilder, AnimatedBuilder — and it also exposes a Stream for code that prefers streams.

Installation #

dependencies:
  property: ^1.0.0

Requires Dart 3.8 / Flutter 3.32 or newer.

Usage #

import 'package:property/property.dart';

final Property<int> counter = Property<int>(0);

PropertyBuilder<int>(
  property: counter,
  builder: (BuildContext context, int value, Widget? child) => Text('$value'),
)

counter.value++;              // or
counter.update((int v) => v + 1);

Dispose it with the widget that owns it:

@override
void dispose() {
  counter.dispose();
  super.dispose();
}

Several properties at once #

MultiPropertyBuilder(
  properties: <Listenable>[firstName, lastName],
  builder: (BuildContext context, Widget? child) =>
      Text('${firstName.value} ${lastName.value}'),
)

Derived values #

map returns a read-only property that follows the source. Dispose it too.

final Property<String> label = counter.map((int v) => v.isEven ? 'even' : 'odd');

As a stream #

StreamBuilder<int>(
  stream: counter.stream,
  builder: (context, snapshot) => Text('${snapshot.data}'),
)

Every listener receives the current value immediately, then each change.

Mutable values #

A list edited in place is still equal to itself, so assigning it back notifies nobody. forceValue notifies regardless:

items.value.add(newItem);
items.forceValue(items.value);

API #

Migrating from 0.0.3 #

• Property must be disposed. It never released its StreamController before, so every property leaked one.
• PropertyBuilder's builder takes (context, value, child) and the value is non-nullable. A callback written as (context, value) needs the extra parameter; the value no longer needs a !.
• stream gives every listener the current value. Previously only the first listener did, because the value was pushed from the broadcast controller's onListen.
• Property is now a ChangeNotifier / ValueListenable.

License #

MIT.