RtConsumer

The RtConsumer widget obtains the dependency provided by the closest RtProvider widget and rebuilds itself whenever there are changes in the dependency or any defined states.

Note

RtConsumer is similar to the BuildContext.use and BuildContext.watch functions, but it is designed to be used within the widget tree.

Syntax

RtConsumer<T>({
  Key? key,
  String? id,
  Widget? child,
  bool listenAll = false,
  List<RtState> listenStates(
    T instance,
  ),
  required Widget builder(
    BuildContext context,
    T instance,
    Widget? child,
  ),
})

Properties

• key: An optional Key to use for identifying the widget.
• id: An optional identifier for the dependency. If omitted, the dependency will be located by its type( T ).
• child: An optional Widget that remains static while the widget tree is rebuilt. It is passed to the builder function if it is defined.
• listenAll: A boolean that determines whether to listen to all states provided by the T dependency. If set to true , the listenStates function is ignored. The default value is false .
• listenStates : An optional function that returns a list of state( RtState ) to listen to. It takes the instance of the T dependency as an argument. If omitted, the listenAll property is checked.
• builder : A function that rebuilds a widget depending on the RtConsumer . It receives the following arguments:
  • context: The BuildContext of the RtConsumer widget.
  • instance: The instance of T dependency provided by the closest RtProvider widget.
  • child: The child widget passed to RtConsumer .

Usage

Basic Usage

To use RtConsumer , you need to provide the T dependency using the RtProvider widget.

Note

Ensure that the RtProvider widget is placed higher in the widget tree than any RtConsumer instances needing access to the T dependency.

Here’s an example of how to use it:

• counter.dart
• main.dart
• counter_view.dart
• counter_controller.dart

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_controller.dart';

class Counter extends StatelessWidget {
  const Counter({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Locale the `CounterController` dependency
    return RtConsumer<CounterController>(
      builder: (context, counterController, child) {
        return Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            ElevatedButton(
              onPressed: counterController.decrement,
              child: const Icon(Icons.remove),
            ),
            const SizedBox(width: 8),
            Text("${counterController.count}"),
            const SizedBox(width: 8),
            ElevatedButton(
              onPressed: counterController.increment,
              child: const Icon(Icons.add),
            ),
          ],
        );
      },
    );
  }
}

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_view.dart';
import 'counter_controller.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // Provide the `CounterController` dependency to the widget tree
      home: RtProvider.lazy(
        () => CounterController(),
        builder: (context, child) {
          return CounterView();
        },
      ),
    );
  }
}

import 'package:flutter/material.dart';
import 'counter.dart';

class CounterView extends StatelessWidget {
  const CounterView({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Counter"),
      ),
      body: Center(
        child: Counter(),
      ),
    );
  }
}

import 'package:reactter/reactter.dart';

class CounterController {
  // Create a reactive state using the `Signal` class
  final count = Signal(0);

  void increment() {
    count.value++;
  }

  void decrement() {
    count.value--;
  }
}

In the example above, RtConsumer is used only to access the CounterController dependency within the Counter widget. Consequently, it does not rebuild whenever there are changes in the count state of the CounterController dependency.

Note

For specific state listening, you can use the listenStates property(see the Listening to specific states section).

Alternatively, you can set the listenAll property to true to listen to all states provided by the CounterController dependency(see the Listening to all states section).

Listening to all state

To listen to all states, set the listenAll property to true . This ensures that RtConsumer rebuilds whenever any state in the dependency changes.

Caution

Using the listenAll property indiscriminately is not recommended, especially when some states are not directly involved in rendering the widget subtree. Instead, it is advisable to use listenStates to specifically define which states to listen(see the Listening to specific states section).

Here’s an example of how to use it:

• counter.dart
• main.dart
• counter_view.dart
• counter_controller.dart

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_controller.dart';

class Counter extends StatelessWidget {
  const Counter({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Listens to all states provided by the `CounterController` dependency
    // and rebuilds whenever there are changes any state of the `CounterController` dependency
    return RtConsumer<CounterController>(
      listenAll: true,
      builder: (context, counterController, child) {
        return Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            ElevatedButton(
              onPressed: counterController.decrement,
              child: const Icon(Icons.remove),
            ),
            const SizedBox(width: 8),
            Text("${counterController.count}"),
            const SizedBox(width: 8),
            ElevatedButton(
              onPressed: counterController.increment,
              child: const Icon(Icons.add),
            ),
          ],
        );
      },
    );
  }
}

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_view.dart';
import 'counter_controller.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // Provide the `CounterController` dependency to the widget tree
      home: RtProvider.lazy(
        () => CounterController(),
        builder: (context, child) {
          return CounterView();
        },
      ),
    );
  }
}

import 'package:flutter/material.dart';
import 'counter.dart';

class CounterView extends StatelessWidget {
  const CounterView({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Counter"),
      ),
      body: Center(
        child: Counter(),
      ),
    );
  }
}

import 'package:reactter/reactter.dart';

class CounterController {
  // Create a reactive state using the `Signal` class
  final count = Signal(0);

  void increment() {
    count.value++;
  }

  void decrement() {
    count.value--;
  }
}

In the example above, RtConsumer will trigger a rebuild of the widget subtree(the Row widget and each of its children) whenever there are changes in any state of the CounterController dependency.

So, that approach lacks performance efficient. It is advisable to optimize by selectively wrapping only the necessary widgets with RtConsumer , utilizing either active or non-active listening as appropriate, e.g.:

• counter.dart
• main.dart
• counter_view.dart
• counter_controller.dart

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_controller.dart';

class Counter extends StatelessWidget {
  const Counter({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Locale the `CounterController` dependency
    return RtConsumer<CounterController>(
      builder: (context, counterController, child) {
        return Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            ElevatedButton(
              onPressed: counterController.decrement,
              child: const Icon(Icons.remove),
            ),
            const SizedBox(width: 8),
            // Listens to all states provided by the `CounterController` dependency
            // and rebuilds whenever there are changes any state of the `CounterController` dependency
            RtConsumer<CounterController>(
              listenAll: true,
              builder: (context, counterController, child) {
                return Text("${counterController.count}");
              },
            ),
            const SizedBox(width: 8),
            ElevatedButton(
              onPressed: counterController.increment,
              child: const Icon(Icons.add),
            ),
          ],
        );
      },
    );
  }
}

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_view.dart';
import 'counter_controller.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // Provide the `CounterController` dependency to the widget tree
      home: RtProvider.lazy(
        () => CounterController(),
        builder: (context, child) {
          return CounterView();
        },
      ),
    );
  }
}

import 'package:flutter/material.dart';
import 'counter.dart';

class CounterView extends StatelessWidget {
  const CounterView({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Counter"),
      ),
      body: Center(
        child: Counter(),
      ),
    );
  }
}

import 'package:reactter/reactter.dart';

class CounterController {
  // Create a reactive state using the `Signal` class
  final count = Signal(0);

  void increment() {
    count.value++;
  }

  void decrement() {
    count.value--;
  }
}

Listening to specific states

To listen to specific states, use the listenStates property. Define a function that returns a list of the states you want to listen to. This ensures that RtConsumer rebuilds only when the specified states change.

Here’s an example of how to use it:

• counter.dart
• main.dart
• counter_view.dart
• counter_controller.dart

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_controller.dart';

class Counter extends StatelessWidget {
  const Counter({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Locale the `CounterController` dependency
    return RtConsumer<CounterController>(
      builder: (context, counterController, child) {
        return Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            ElevatedButton(
              onPressed: counterController.decrement,
              child: const Icon(Icons.remove),
            ),
            const SizedBox(width: 8),
            // Observe the `count` property of the `counterController`
            // and rebuild the widget tree when the `count` value changes
            RtConsumer<CounterController>(
              listenStates: (counterController) => [counterController.count],
              builder: (context, counterController, child) {
                return Text("${counterController.count}");
              },
            ),
            const SizedBox(width: 8),
            ElevatedButton(
              onPressed: counterController.increment,
              child: const Icon(Icons.add),
            ),
          ],
        );
      },
    );
  }
}

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_view.dart';
import 'counter_controller.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // Provide the `CounterController` dependency to the widget tree
      home: RtProvider.lazy(
        () => CounterController(),
        builder: (context, child) {
          return CounterView();
        },
      ),
    );
  }
}

import 'package:flutter/material.dart';
import 'counter.dart';

class CounterView extends StatelessWidget {
  const CounterView({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Counter"),
      ),
      body: Center(
        child: Counter(),
      ),
    );
  }
}

import 'package:reactter/reactter.dart';

class CounterController {
  // Create a reactive state using the `Signal` class
  final count = Signal(0);

  void increment() {
    count.value++;
  }

  void decrement() {
    count.value--;
  }
}

In the example above, RtConsumer will trigger a rebuild of the Text widget whenever there are changes in the count state of the CounterController dependency.

Using id

RtConsumer offers the id property to locate the T dependency by its identifier. This is useful when you have multiple instances of the same dependency type and need to specify which one to use.

Here’s an example of how to use it:

• counter.dart
• counter_view.dart
• counter_view.dart
• counter_controller.dart

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_controller.dart';

class Counter extends StatelessWidget {
  final String? id;

  const Counter({Key? key, this.id}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Locale the `CounterController` dependency
    return RtConsumer<CounterController>(
      id: id,
      builder: (context, counterController, child) {
        return Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            ElevatedButton(
              onPressed: counterController.decrement,
              child: const Icon(Icons.remove),
            ),
            const SizedBox(width: 8),
            // Observe the `count` property of the `counterController`
            // and rebuild the widget tree when the `count` value changes
            RtConsumer<CounterController>(
              id: id,
              listenStates: (counterController) => [counterController.count],
              builder: (context, counterController, child) {
                return Text("${counterController.count}");
              },
            ),
            const SizedBox(width: 8),
            ElevatedButton(
              onPressed: counterController.increment,
              child: const Icon(Icons.add),
            ),
          ],
        );
      },
    );
  }
}

import 'package:flutter/material.dart';
import 'counter.dart';

class CounterView extends StatelessWidget {
  const CounterView({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Counter"),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Counter(id: 'counter1'),
            const SizedBox(height: 8),
            const Counter(id: 'counter2'),
          ],
        ),
      ),
    );
  }
}

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_view.dart';
import 'counter_controller.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: RtMultiProvider(
        [
          RtProvider(() => CounterController(), id: 'counter1'),
          RtProvider(() => CounterController(), id: 'counter2'),
        ],
        builder: (context, child) {
          return CounterView();
        },
      ),
    );
  }
}

import 'package:reactter/reactter.dart';

class CounterController {
  // Create a reactive state using the `Signal` class
  final count = Signal(0);

  void increment() {
    count.value++;
  }

  void decrement() {
    count.value--;
  }
}

In the example above, RtConsumer uses the id property to locate the CounterController dependency by the counter1 and counter2 identifiers.

Note

Ensure that the id property is located in the RtProvider widget that provides the T dependency.

Using child

RtConsumer offers the child property to pass a widget that is independent of the RtConsumer and is passed to the builder function. This is useful when you want to reuse a widget that does not need to rebuild when the dependency changes.

Note

The child argument can’t accessed to the dependency instance.

Here’s an example of how to use it:

• counter.dart
• counter_view.dart
• main.dart
• counter_controller.dart

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_controller.dart';

class Counter extends StatelessWidget {
  final String? id;

  const Counter({Key? key, this.id}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Locale the `CounterController` dependency
    return RtConsumer<CounterController>(
      id: id,
      builder: (context, counterController, child) {
        return Row(
          mainAxisSize: MainAxisSize.min,
          children: [
            ElevatedButton(
              onPressed: counterController.decrement,
              child: const Icon(Icons.remove),
            ),
            const SizedBox(width: 8),
            // Observe the `count` property of the `counterController`
            // and rebuild the widget tree when the `count` value changes
            RtConsumer<CounterController>(
              id: id,
              listenStates: (counterController) => [counterController.count],
              child: Text("Count[$id]: "),
              builder: (context, counterController, child) {
                return Row(
                  children: [
                    child!,
                    Text("${counterController.count}"),
                  ],
                );
              },
            ),
            const SizedBox(width: 8),
            ElevatedButton(
              onPressed: counterController.increment,
              child: const Icon(Icons.add),
            ),
          ],
        );
      },
    );
  }
}

import 'package:flutter/material.dart';
import 'counter.dart';

class CounterView extends StatelessWidget {
  const CounterView({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Counter"),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Counter(id: 'counter1'),
            const SizedBox(height: 8),
            const Counter(id: 'counter2'),
          ],
        ),
      ),
    );
  }
}

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_view.dart';
import 'counter_controller.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: RtMultiProvider(
        [
          RtProvider(() => CounterController(), id: 'counter1'),
          RtProvider(() => CounterController(), id: 'counter2'),
        ],
        builder: (context, child) {
          return CounterView();
        },
      ),
    );
  }
}

import 'package:reactter/reactter.dart';

class CounterController {
  // Create a reactive state using the `Signal` class
  final count = Signal(0);

  void increment() {
    count.value++;
  }

  void decrement() {
    count.value--;
  }
}

In the example above, RtConsumer uses the child property to pass the Text widget to the builder function.