BuildContext.select

BuildContext.select is a method that computes a value whenever the selected states change and registers the current widget as a listener for these changes. Consequently, each time the selected states change, the value is recalculated and if it is different from the previous one, the widget is automatically notified and rebuilt.

Tip

BuildContext.select is useful when you need to render using a computed value based on multiple states. This aproach is more efficient than using BuildContext.watch because it avoids unnecessary rebuilds.

Show me an example and explanation

[...]
build(BuildContext context) {
  final product = context.watch<Product>(
    (product) => [product.price, product.quantity],
  );
  final total = product.price.value + product.quantity.value;

  return Text("Total: $total");
}

// is equivalent to

[...]
build(BuildContext context) {
  final total = context.select<Product>(
    (product, $) {
      // The `$(...)` syntax is used to select a specific state to listen for changes.
      return $(product.price).value + $(product.quantity).value;
    },
  );

  return Text("Total: $total");
}

In the example above, we use context.watch and context.select to calculate the total price of a product based on its unit price and quantity. These methods update the UI when certain dependencies change, but they have different performance implications.

When using context.watch , the widget will rebuild whenever any of the dependencies change, even if the change in state does not affect the calculated value. This can lead to unnecessary rebuilds and reduced performance.

In contrast, context.select allows you to listen for specific state changes and only rebuilds when the calculated value (total) changes. This approach is more efficient as it avoids unnecessary rebuilds, leading to better performance.

Syntax & description

V context.select<T, V>(
  V computeValue(T instance, RtState select(RtState state)),
  [String? id],
);

• context: The BuildContext object, which provides information about the current widget in the tree.
• T : The type of the dependency you want to select. It is used to locate the dependency from the nearest ancestor provider.
• V : The type of the value you want to compute. It is the return type of the computeValue function.
• computeValue : A function that computes the value based on the selected states. It takes two arguments:
  • instance: The instance of the dependency of type T .
  • select : A function that allows you to wrap the state( RtState ) to be listened for changes and returns it.
• id: An optional identifier for the T dependency. If omitted, the dependency will be located by its type ( T ).

Tip

It’s a good idea to name the select parameter to something more simple and shorter like $ to make it easier to read and understand the selector function when you have multiple states to select.

RtSelector<UserController, String>(
  selector: (inst, $) => $(inst.firstName).value + ' ' + $(inst.lastName).value,
  builder: (context, inst, fullName, child) {
    return Text("Full name: $fullName");
  },
)

Usage

This following example demonstrates how to use BuildContext.select :

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

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

class CounterDivisible extends StatelessWidget {
  final int byNum;

  const CounterDivisible({Key? key, required this.byNum}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Select the `count` state from the `CounterController`,
    // calculate if the `count` is divisible by num(`byNum`)
    // and rebuild the widget tree when the value(`isDivisibleByNum`) changes
    final isDivisibleByNum = context.select<CounterController, bool>(
      (counterController, $) => $(counterController.count).value % byNum == 0,
    );

    return Text(
      isDivisibleByNum ? "Divisible by $byNum" : "Not divisible by $byNum",
    );
  }
}

import 'package:flutter/material.dart';
import 'counter.dart';
import 'counter_divisible.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(),
            SizedBox(height: 8),
            const CounterDivisible(byNum: 2),
            SizedBox(height: 8),
            const CounterDivisible(byNum: 3),
            SizedBox(height: 8),
            const CounterDivisible(byNum: 5),
          ],
        ),
      ),
    );
  }
}

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: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 this example, checks if the count state from CounterController is divisible by a specified number (byNum). The BuildContext.select method is used to perform this check and rebuild the widget tree whenever the divisibility status changes.