Pub Version Flutter CI codecov

A flutter package providing extension methods to trigger a rebuild on change in a Listenable (ChangeNotifier, ValueNotifier, etc).

There is a plan to support Stream too. Stay tuned!

What is Grab?

Grab is like a method version of ValueListenablebuiler, AnimatedBuilder or ListenableBuilder.

If grab() or grabAt() is called on a Listenable, the widget associated with the provided BuildContext is rebuilt whenever the Listenable (or a selected value) is updated, and as a result, the method "grab"s and returns the updated value.

class UserProfile extends StatelessWidget {
  const UserProfile();

  @override
  Widget build(BuildContext context) {
    final userName = userNotifier.grabAt(context, (state) => state.name);
    return Text(userName);
  }
}

Good for state management

What this package does is only rebuild a widget according to changes in a Listenable as stated above. Despite such simplicity, however, it becomes a powerful state management tool if combined with some DI package such as get_it or pot.

The Listenable does not have to be passed down the widget tree. Because Grab works as long as a Listenable is available in any way when grab() or grabAt() is used, you can use your favourite DI solution to pass around the Listenable.

Motivation

The blog post below by someone else gave me the inspiration for this package. It shows a picture of how simple state management could be.

Grab instead of ValueListenableBuilder used in the article, combined with some sort of DI, lets you focus on creating a good app with no difficulty understanding how to use it. The simplicity is an advantage over other packages with a larger API surface and too much functionality.

Supported Listenables

Anything that inherits the Listenable class:

  • ChangeNotifier
  • ValueNotifier
  • TextEditingController
  • Animation / AnimationController
  • ScrollController
  • etc.

It is recommended to use Grab with subtypes of ValueListenable for type safety. Please see the related section later in this document.

Examples

Usage

Getting started

The Grab widget is necessary somewhere accessible via the tree from any widget where grab extension methods are used. It is recommended the root widget is wrapped as follows.

import 'package:grab/grab.dart';
...

void main() {
  runApp(
    const Grab(child: MyApp()),
  );
}

Extension methods

grab() and grabAt() are available as extension methods of Listenable and ValueListenable. They are similar to watch() and select() of package:provider.

Make sure to have the Grab widget up in the tree. A GrabMissingError is thrown otherwise.

grab()

grab() listens for changes in the Listenable that the method is called on. Every time there is a change, it rebuilds the widget associated with the provided BuildContext.

final notifier = ValueNotifier(0);

@override
Widget build(BuildContext context) {
  final count = notifier.grab(context);
  return Text('$count');
}

What is returned from the method depends on the type of the Listenable which the method is called on:

  • ValueListenable (e.g. ValueNotifier, TextEditingController)
    • The value of the ValueListenable is returned.
  • Listenable other than ValueListenable (e.g. ChangeNotifier, ScrollController)
    • The Listenable itself is returned.

In the above example, the Listenable is a ValueNotifier, which is a subtype of ValueListenable, so the count returned by grab() is the value of ValueNotifier.

This is a little tricky, but has been designed that way for convenience.

grabAt()

grabAt() allows you to choose a value to be returned. The value is also used to evaluate the necessity of a rebuild.

  • The widget is rebuilt only when there is a change in the value returned by the selector, which is a callback function passed as the second argument.
  • grabAt() returns the value selected by the selector.
final notifier = ValueNotifier(
  Item(name: 'Milk', quantity: 3),
);

@override
Widget build(BuildContext context) {
  final name = notifier.grabAt(context, (item) => item.name);
  return Text(name);
}

If the Listenable is ValueListenable or its subtype, the selector receives its value. Otherwise, it receives the Listenable itself.

In the above example, the Listenable is a ValueNotifier, which is a subtype of ValueListenable, so its value (an Item having name and quantity) is passed to the selector. The widget is rebuilt when name is updated but not when only quantity is updated, and the selected value (the value of name) is returned.

Type safety

The extension methods are more type-safe when used with a subtype of ValueListenable (e.g. ValueNotifier).

ValueNotifier:

final valueNotifier = ValueNotifier(MyState);

// The type is inferred.
final state = valueNotifier.grab(context);
final prop = valueNotifier.grabAt(context, (state) => state.prop);

ChangeNotifier (not type-safe):

final changeNotifier = MyChangeNotifier();

// The type is not inferred, so needs to be annotated.
final notifier = changeNotifier.grab<MyChangeNotifier>(context);
final prop = changeNotifier.grabAt(context, (MyChangeNotifier notifier) => notifier.prop);

// Specifying a wrong type raises an error only at runtime.
changeNotifier.grab<AnotherChangeNotifier>(context);

Tips

Value returned by selector

The value is not limited to a field value of the Listenable. It can be anything as long as it is possible to evaluate the equality with its previous value using the == operator.

final hasEnough = notifier.grabAt(context, (item) => item.quantity > 5);

Supposing that the quantity was 3 in the previous build and has changed to 2 now, the widget is not rebuilt because the value returned by the selector has remained false.

Getting a value without a rebuild

Grab is a package for rebuilding a widget, so it does not provide an equivalent of read() of the provider package. If you need a field value of a Listenable, you can just take it out of the Listenable without Grab.

DI (Dependency Injection)

Grab does not care about how a Listenable is passed around, so you can use your favourite DI solution to inject ones and get them anywhere in any layer.

Pottery by the same author is a good option for this purpose. It is a package that helps you use Pot (a single-type DI container) in Flutter. Grab used together with it provides a similar experience to using package:provider but with more flexibility in that pots are available anywhere while their lifetime is managed according to the lifecycle of widgets.

Libraries

grab