Skip to content

Commit 95c4391

Browse files
Mairramergemini-code-assist[bot]parlough
authored
Add breaking change page for DropdownButton enabled property (#13430)
Description of what this PR is changing or adding, and why: Adds a breaking change page for the new `enabled` property logic on `DropdownButton` and `DropdownButtonFormField`. This explains why the `onChanged` callback is no longer required and clarifies the fallback behavior for backward compatibility. It also guides developers on how to properly separate interactive state (`enabled`) from widget behavior (`onChanged`), highlighting what the `dart fix` covers and what requires manual migration (like conditional logic). Issues fixed by this PR (if any): N/A but related to flutter/flutter#57953 PRs or commits this PR depends on (if any): Depends on flutter/flutter#182419 ## Presubmit checklist - [x] If you are unwilling, or unable, to sign the CLA, even for a _tiny_, one-word PR, please file an issue instead of a PR. - [x] If this PR is not meant to land until a future stable release, mark it as draft with an explanation. - [x] This PR follows the [Google Developer Documentation Style Guidelines](https://developers.google.com/style)—for example, it doesn't use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first-person pronouns). - [x] This PR uses [semantic line breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks) of 80 characters or fewer. --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Co-authored-by: Parker Lougheed <[email protected]>
1 parent 59c4ea1 commit 95c4391

2 files changed

Lines changed: 153 additions & 0 deletions

File tree

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: Added enabled property and made onChanged optional for DropdownButton
3+
description: >-
4+
DropdownButton and DropdownButtonFormField now support an explicit enabled
5+
property, and their onChanged callbacks are no longer required.
6+
---
7+
8+
{% render "docs/breaking-changes.md" %}
9+
10+
## Summary
11+
12+
`DropdownButton` and `DropdownButtonFormField` now include
13+
an `enabled` property to explicitly manage their interactive state,
14+
and the `onChanged` callback is no longer marked as `required`.
15+
16+
## Background
17+
18+
Previously, `DropdownButton` and `DropdownButtonFormField` didn't
19+
have an `enabled` parameter.
20+
The only way to disable the dropdown
21+
(graying it out and making it non-interactive) was to
22+
pass `null` to the `required` `onChanged` callback.
23+
This led to unintuitive code when trying to
24+
dynamically enable or disable the button,
25+
forcing developers to write conditional expressions for the callback itself,
26+
such as `onChanged: condition ? (value) { ... } : null`.
27+
28+
To improve this API, a dedicated `enabled` property was introduced,
29+
and `onChanged` was made optional.
30+
31+
The `enabled` property is optional.
32+
Making it mandatory introduces a massive breaking change that
33+
breaks nearly every existing `DropdownButton` implementation in
34+
the Flutter ecosystem.
35+
Instead, to preserve backward compatibility,
36+
if the `enabled` argument isn't explicitly provided,
37+
the button determines its state by falling back to whether
38+
`onChanged` is provided (that is, it's enabled if `onChanged != null`,
39+
and disabled if `onChanged == null`).
40+
41+
The minor breaking change here is structural:
42+
while the old conditional `onChanged` pattern technically
43+
still works due to the fallback logic,
44+
developers are encouraged to migrate to the clearer API by
45+
explicitly using the `enabled` property.
46+
47+
## Migration guide
48+
49+
If you previously disabled your `DropdownButton` by
50+
conditionally passing `null` to `onChanged`,
51+
migrate to the new `enabled` property.
52+
This cleanly separates the state of the widget (enabled/disabled) from
53+
its behavior (the callback).
54+
55+
To automatically migrate your code for simple cases
56+
(such as statically passing `null`), run the following command:
57+
58+
```console
59+
$ dart fix --apply
60+
```
61+
62+
:::important
63+
Note that `dart fix` will not automatically migrate cases where `onChanged`
64+
is set using conditional logic. For those, you must update your code manually.
65+
:::
66+
67+
### Case 1: Statically disabled dropdown {: #case-1-statically-disabled }
68+
69+
For simple cases where a dropdown is permanently disabled,
70+
you can now simply omit `onChanged` and use `enabled: false`.
71+
72+
Code before migration:
73+
74+
```dart
75+
final disabledDropdown = DropdownButton<String>(
76+
value: 'Option 1',
77+
items: const [
78+
DropdownMenuItem(value: 'Option 1', child: Text('Option 1')),
79+
],
80+
onChanged: null, // This was the only way to disable it
81+
);
82+
```
83+
84+
Code after migration:
85+
86+
```dart diff
87+
final disabledDropdown = DropdownButton<String>(
88+
value: 'Option 1',
89+
items: const [
90+
DropdownMenuItem(value: 'Option 1', child: Text('Option 1')),
91+
],
92+
- onChanged: null, // This was the only way to disable it
93+
+ enabled: false,
94+
);
95+
```
96+
97+
### Case 2: Conditionally disabled dropdown {: #case-2-conditionally-disabled }
98+
99+
The recommended best practice is to separate the callback from
100+
the interactive state by using the `enabled` property directly.
101+
102+
Code before migration:
103+
104+
```dart
105+
final conditionalDropdown = DropdownButton<String>(
106+
value: 'Option 1',
107+
items: const [
108+
DropdownMenuItem(value: 'Option 1', child: Text('Option 1')),
109+
],
110+
onChanged: condition ? (value) { ... } : null,
111+
);
112+
```
113+
114+
Code after migration:
115+
116+
```dart diff
117+
final conditionalDropdown = DropdownButton<String>(
118+
value: 'Option 1',
119+
items: const [
120+
DropdownMenuItem(value: 'Option 1', child: Text('Option 1')),
121+
],
122+
- onChanged: condition ? (value) { ... } : null,
123+
+ onChanged: (value) { ... },
124+
+ enabled: condition,
125+
);
126+
```
127+
128+
## Timeline
129+
130+
Landed in version: 3.44.0-1.0.pre-629<br>
131+
In stable release: Not yet
132+
133+
## References
134+
135+
API documentation:
136+
137+
* [`DropdownButton`][]
138+
* [`DropdownButtonFormField`][]
139+
140+
Relevant issues:
141+
142+
* [Why is DropdownButtonFormField's onChanged required?][issue-57953]
143+
144+
Relevant PRs:
145+
146+
* [Update DropdownButton enabled property logic][]
147+
148+
[`DropdownButton`]: {{site.api}}/flutter/material/DropdownButton-class.html
149+
[`DropdownButtonFormField`]: {{site.api}}/flutter/material/DropdownButtonFormField-class.html
150+
[issue-57953]: {{site.repo.flutter}}/issues/57953
151+
[Update DropdownButton enabled property logic]: {{site.repo.flutter}}/pull/182419

‎sites/docs/src/content/release/breaking-changes/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,10 @@ They're sorted by release and listed in alphabetical order:
3737
### Not yet released to stable
3838

3939
* [Large screen orientation and resizability restrictions ignored on Android 17][]
40+
* [Added enabled property and made onChanged optional for DropdownButton][]
4041

4142
[Large screen orientation and resizability restrictions ignored on Android 17]: /release/breaking-changes/android-large-screens-restrictions-ignored
43+
[Added enabled property and made onChanged optional for DropdownButton]: /release/breaking-changes/dropdownbutton-enabled-property
4244

4345
<a id="released-in-flutter-344" aria-hidden="true"></a>
4446
### Released in Flutter 3.44

0 commit comments

Comments
 (0)