Clarify why value was changed to valueListenable

[xvrh]

In v3.0.0, the value setter was replaced by valueListenable. This is a breaking change that requires a non-trivial migration for existing projects. Furthermore, this move deviates from the standard value/onChanged pattern found in Flutter’s native DropdownButtonFormField.

Could you provide some insight into the reasoning behind this change? Specifically, why was this implemented as a mandatory change rather than an optional alternative?

Small note: often in Flutter this kind of property is called controller I think.

[AhmedLSayed9]

Hey @xvrh,

There were a few reasons behind this decision, the bigger driver was multi-select support (see #167, #121). The old workaround used a StatefulBuilder per item, where each item only had access to its own menuSetState. This made "select all" / "deselect all" not feasible — there was no way to rebuild all checkmarks at once from a single tap. multiValueListenable solves this cleanly since it's a single shared listenable that all items can observe, while also handling other stuff internally like the initial scroll, and valueListenable was introduced alongside it to keep the API consistent. Having one use ValueListenable and the other use a plain value would have been inconsistent.

As a bonus, the old value pattern required holding state externally and calling setState on every selection, rebuilding the entire parent even when nothing else needed to update. valueListenable handles this inside the widget itself — you hand it a ValueNotifier (already a well-understood Flutter primitive), and internally DropdownButton2 uses a ValueListenableBuilder to wrap only the parts that depend on the value, so only those rebuild.

Here's a minimal example illustrating the difference:

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

void main() => runApp(const MaterialApp(home: MyPage()));

const items = ['Item1', 'Item2', 'Item3'];

class MyPage extends StatefulWidget {
  const MyPage({super.key});

  @override
  State<MyPage> createState() => _MyPageState();
}

class _MyPageState extends State<MyPage> {
  // Flutter's DropdownButton — state held externally
  String? selectedValue;

  // DropdownButton2 — state held in ValueNotifier
  final valueListenable = ValueNotifier<String?>(null);

  @override
  Widget build(BuildContext context) {
    debugPrint('MyPage rebuilt');
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            // Requires setState, rebuilds entire MyPage on every selection
            DropdownButton<String>(
              value: selectedValue,
              items: items.map((e) => DropdownMenuItem(value: e, child: Text(e))).toList(),
              onChanged: (value) => setState(() => selectedValue = value),
            ),
            const SizedBox(height: 16),
            // No setState, only the dropdown relevant parts rebuild internally
            DropdownButton2<String>(
              valueListenable: valueListenable,
              items: items.map((e) => DropdownItem(value: e, child: Text(e))).toList(),
              onChanged: (value) => valueListenable.value = value,
            ),
          ],
        ),
      ),
    );
  }
}

Why not keep both?
This was raised in #249. Supporting value alongside valueListenable/multiValueListenable would complicate both the API implementation and the codebase — the widget would need to handle conflicts between them and decide which takes precedence, and it doubles the maintenance and documentation burden. It also leaves users confused about which to use and when.

On the controller naming: Flutter controllers like TextEditingController and ScrollController are concrete classes with some internal state, specialized methods, and a required dispose(). Our parameter is just ValueListenable<T> — a simple abstract interface that any implementation can satisfy. Flutter uses the same name for ValueListenableBuilder.

Hope that clears things up!

[AhmedLSayed9]

I just added a migration guide for value → valueListenable to the v3.0.0 CHANGELOG entry — should make upgrading from 2.x easier.