docs: clarify dropdown menu text clearing #179676

kazbeksultanov · 2025-12-10T11:06:49Z

The documentation for DropdownMenu's controller and initialSelection properties has been updated. It now explicitly states that clearing the text field requires using a TextEditingController's clear() method, and that setting initialSelection to null will not clear the text. A code snippet demonstrating how to clear the text field has also been added.

Fix for: #177599

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

The documentation for `DropdownMenu`'s `controller` and `initialSelection` properties has been updated. It now explicitly states that clearing the text field requires using a `TextEditingController`'s `clear()` method, and that setting `initialSelection` to null will not clear the text. A code snippet demonstrating how to clear the text field has also been added.

gemini-code-assist

Code Review

This pull request clarifies the documentation for DropdownMenu's controller and initialSelection properties, explaining how to programmatically clear the text field. The changes are clear and helpful, adding explicit instructions and a code snippet. I've suggested a couple of minor wording tweaks to further improve clarity and consistency in the documentation.

I am having trouble creating individual review comments. Click here to see my feedback.

packages/flutter/lib/src/material/dropdown_menu.dart (401-406)

For improved clarity and consistency, I suggest a couple of minor wording changes in the documentation for initialSelection.

On line 402, explicitly use [initialSelection] instead of this to avoid any ambiguity.
On line 405, rephrasing to ...call its [TextEditingController.clear] method. would make it more consistent with the documentation for the controller property.

/// text field only if the new value exists in [dropdownMenuEntries]. Setting
/// [initialSelection] to null does NOT clear the text field.
///
/// To programmatically clear the text field, use a [TextEditingController]
/// and call its [TextEditingController.clear] method. See [controller] for more
/// information.

@tool

The `{@tool snippet}` and `{@end-tool}` tags are unnecessary for a simple code block in the documentation.

QuncCccccc

Thanks for adding the doc improvements! Overall looks good! Left some comments below.

packages/flutter/lib/src/material/dropdown_menu.dart

kazbeksultanov · 2025-12-19T08:50:15Z

@QuncCccccc resolved the comments 👍

kazbeksultanov · 2025-12-22T10:41:25Z

@QuncCccccc related to Linux analyze check. For me, it doesn't make any sense.
It's all in 1 line, and seems like it's considering it to be part of code, not the doc comment I believe.

Is there any suggestion how to fix it?

Or I can remove the dart example at all, even though I see it to be better.

packages/flutter/lib/src/material/dropdown_menu.dart:439:7: Functions must have an explicit list of parameters (top-level declaration) (missing_function_parameters)
packages/flutter/lib/src/material/dropdown_menu.dart:439:7: Missing type annotation (top-level declaration) (strict_top_level_inference)
packages/flutter/lib/src/material/dropdown_menu.dart:439:7: The name 'myController' is already defined (top-level declaration) (duplicate_definition)
packages/flutter/lib/src/material/dropdown_menu.dart:439:19: A function body must be provided (top-level declaration) (missing_function_body)
packages/flutter/lib/src/material/dropdown_menu.dart:439:19: Expected a method, getter, setter or operator declaration (top-level declaration) (expected_executable)
packages/flutter/lib/src/material/dropdown_menu.dart:439:20: Missing type annotation (top-level declaration) (strict_top_level_inference)
packages/flutter/lib/src/material/dropdown_menu.dart:439:27: A function body must be provided (top-level declaration) (missing_function_body)

kazbeksultanov · 2025-12-22T11:48:53Z

Removed the example code and Linux analyze passed. @QuncCccccc what do you think, is it ok?

QuncCccccc

LGTM. Thanks for adding the doc enhancement.

packages/flutter/lib/src/material/dropdown_menu.dart

loic-sharma

LGTM once this comment is addressed: #179676 (comment)

Co-authored-by: Loïc Sharma <737941+loic-sharma@users.noreply.github.com>

…9676)

Roll Flutter from 6ff7f30 to 60d8165 (32 revisions) flutter/flutter@6ff7f30...60d8165 2025-12-29 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from xn1U9DUFEpB4f6vG-... to DdllqZRZYriOd7Q8v... (flutter/flutter#180356) 2025-12-28 engine-flutter-autoroll@skia.org Roll Dart SDK from 17d51009282c to df175c998021 (1 revision) (flutter/flutter#180349) 2025-12-28 engine-flutter-autoroll@skia.org Roll Dart SDK from d4a92c2c69bf to 17d51009282c (1 revision) (flutter/flutter#180346) 2025-12-28 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from jVkEEUxyGeemuu2HE... to xn1U9DUFEpB4f6vG-... (flutter/flutter#180343) 2025-12-27 engine-flutter-autoroll@skia.org Roll Dart SDK from 3b84125003a1 to d4a92c2c69bf (1 revision) (flutter/flutter#180331) 2025-12-27 engine-flutter-autoroll@skia.org Roll Skia from e6e535aec613 to c29a475066f5 (1 revision) (flutter/flutter#180322) 2025-12-27 ahmedsameha1@gmail.com Make sure that a WidgetsApp doesn't crash in 0x0 environment (flutter/flutter#180224) 2025-12-27 ahmedsameha1@gmail.com Make sure that an AnimatedSize doesn't crash in 0x0 environment (flutter/flutter#180174) 2025-12-27 ahmedsameha1@gmail.com Make sure that an AnimatedGrid doesn't crash in 0x0 environment (flutter/flutter#180159) 2025-12-27 ahmedsameha1@gmail.com Make sure that an AnimatedCrossFade does not crash in 0x0 environment (flutter/flutter#180088) 2025-12-27 ahmedsameha1@gmail.com Make sure that an AnimatedList doesn't crash in 0x0 environment (flutter/flutter#180123) 2025-12-26 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from mZlbuHta7S71Quawk... to jVkEEUxyGeemuu2HE... (flutter/flutter#180317) 2025-12-26 engine-flutter-autoroll@skia.org Roll Dart SDK from 6b2c3716be54 to 3b84125003a1 (1 revision) (flutter/flutter#180316) 2025-12-26 engine-flutter-autoroll@skia.org Roll Dart SDK from 18f6751c5ccc to 6b2c3716be54 (1 revision) (flutter/flutter#180252) 2025-12-26 engine-flutter-autoroll@skia.org Roll Skia from 07c59737d265 to e6e535aec613 (1 revision) (flutter/flutter#180303) 2025-12-25 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from 2q71ydbnIhmBUiNOF... to mZlbuHta7S71Quawk... (flutter/flutter#180290) 2025-12-25 engine-flutter-autoroll@skia.org Roll Skia from 6d0a1b03e9c7 to 07c59737d265 (1 revision) (flutter/flutter#180289) 2025-12-25 engine-flutter-autoroll@skia.org Roll Skia from 2b5d93b62a3f to 6d0a1b03e9c7 (1 revision) (flutter/flutter#180279) 2025-12-25 engine-flutter-autoroll@skia.org Roll Skia from 3544942c9d42 to 2b5d93b62a3f (1 revision) (flutter/flutter#180276) 2025-12-24 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from 5EgkVbjGVZmCFPdtR... to 2q71ydbnIhmBUiNOF... (flutter/flutter#180274) 2025-12-24 engine-flutter-autoroll@skia.org Roll Packages from 5e3a766 to 2164da9 (4 revisions) (flutter/flutter#180271) 2025-12-24 engine-flutter-autoroll@skia.org Roll Skia from 988a48f7a944 to 3544942c9d42 (1 revision) (flutter/flutter#180267) 2025-12-24 fluttergithubbot@gmail.com Marks Mac_arm64_mokey native_assets_android to be unflaky (flutter/flutter#180263) 2025-12-24 engine-flutter-autoroll@skia.org Roll Skia from 51a05ce05880 to 988a48f7a944 (1 revision) (flutter/flutter#180256) 2025-12-24 34465683+rkishan516@users.noreply.github.com fix: exclude semantics for disabled dates (flutter/flutter#178981) 2025-12-24 engine-flutter-autoroll@skia.org Roll Skia from 7fe9b93153f8 to 51a05ce05880 (1 revision) (flutter/flutter#180253) 2025-12-24 116356835+AbdeMohlbi@users.noreply.github.com Enhance documentation for sortable column behavior (flutter/flutter#180011) 2025-12-24 engine-flutter-autoroll@skia.org Roll Skia from a0f18947bc1b to 7fe9b93153f8 (4 revisions) (flutter/flutter#180247) 2025-12-23 engine-flutter-autoroll@skia.org Roll Skia from bdb147ae3040 to a0f18947bc1b (2 revisions) (flutter/flutter#180241) 2025-12-23 engine-flutter-autoroll@skia.org Roll Dart SDK from 94b05f717ba3 to 18f6751c5ccc (1 revision) (flutter/flutter#180236) 2025-12-23 kazbek.sultanov.doc@gmail.com docs: clarify dropdown menu text clearing (flutter/flutter#179676) 2025-12-23 flar@google.com New optimized general convex path shadow algorithm (flutter/flutter#178370) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC stuartmorgan@google.com on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md ...

github-actions bot added framework flutter/packages/flutter repository. See also f: labels. f: material design flutter/packages/flutter/material repository. labels Dec 10, 2025

Merge branch 'master' into dropdown_menu_text_clear_doc_enhancement

919a0a9

kazbeksultanov mentioned this pull request Dec 10, 2025

[DropdownMenu] Improve document on how to reset selectedValue #177599

Open

gemini-code-assist bot reviewed Dec 10, 2025

View reviewed changes

dkwingsmt requested a review from QuncCccccc December 10, 2025 19:10

fix: rename controller variable in doc snippet to avoid naming conflict

f8a8f52

kazbeksultanov force-pushed the dropdown_menu_text_clear_doc_enhancement branch from 4847729 to f8a8f52 Compare December 15, 2025 13:33

docs: remove snippet from DropdownMenu controller doc

bc590d9

The `{@tool snippet}` and `{@end-tool}` tags are unnecessary for a simple code block in the documentation.

QuncCccccc reviewed Dec 15, 2025

View reviewed changes

packages/flutter/lib/src/material/dropdown_menu.dart Outdated Show resolved Hide resolved

packages/flutter/lib/src/material/dropdown_menu.dart Outdated Show resolved Hide resolved

packages/flutter/lib/src/material/dropdown_menu.dart Outdated Show resolved Hide resolved

docs: enhance clarity in DropdownMenu text field documentation

f293b42

kazbeksultanov added 2 commits December 22, 2025 13:32

docs: enhance clarity in DropdownMenu text field documentation

afc642c

Merge branch 'master' into dropdown_menu_text_clear_doc_enhancement

11bc783

docs: enhance clarity in DropdownMenu text field documentation

0664e92

QuncCccccc approved these changes Dec 22, 2025

View reviewed changes

loic-sharma reviewed Dec 22, 2025

View reviewed changes

packages/flutter/lib/src/material/dropdown_menu.dart Outdated Show resolved Hide resolved

loic-sharma reviewed Dec 22, 2025

View reviewed changes

packages/flutter/lib/src/material/dropdown_menu.dart Outdated Show resolved Hide resolved

loic-sharma approved these changes Dec 22, 2025

View reviewed changes

kazbeksultanov and others added 2 commits December 23, 2025 18:36

Apply suggestion from @loic-sharma

42d5424

Co-authored-by: Loïc Sharma <737941+loic-sharma@users.noreply.github.com>

Apply suggestion from @loic-sharma

66c0668

Co-authored-by: Loïc Sharma <737941+loic-sharma@users.noreply.github.com>

victorsanni approved these changes Dec 23, 2025

View reviewed changes

victorsanni added the autosubmit Merge PR when tree becomes green via auto submit App label Dec 23, 2025

auto-submit bot added this pull request to the merge queue Dec 23, 2025

Merged via the queue into flutter:master with commit efce5d7 Dec 23, 2025
71 checks passed

flutter-dashboard bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Dec 23, 2025

engine-flutter-autoroll mentioned this pull request Dec 23, 2025

Roll Flutter from d81baabfec4c to efce5d7e5578 (123 revisions) flutter/packages#10673

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 23, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

c0dfd8d

…9676)

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 24, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

6ec6229

…9676)

engine-flutter-autoroll mentioned this pull request Dec 24, 2025

Roll Flutter from 6ff7f300473f to f6144ff9ff84 (11 revisions) flutter/packages#10679

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 24, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

9ef9381

…9676)

engine-flutter-autoroll mentioned this pull request Dec 24, 2025

Roll Flutter from 6ff7f300473f to 4220b8a6cb7b (12 revisions) flutter/packages#10680

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 24, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

42936af

…9676)

engine-flutter-autoroll mentioned this pull request Dec 24, 2025

Roll Flutter from 6ff7f300473f to e255e010da37 (13 revisions) flutter/packages#10681

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 25, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

d02853e

…9676)

engine-flutter-autoroll mentioned this pull request Dec 25, 2025

Roll Flutter from 6ff7f300473f to 404ba9de3bc4 (15 revisions) flutter/packages#10682

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 25, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

4cb8360

…9676)

engine-flutter-autoroll mentioned this pull request Dec 25, 2025

Roll Flutter from 6ff7f300473f to 404ba9de3bc4 (15 revisions) flutter/packages#10684

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 26, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

5e314ba

…9676)

engine-flutter-autoroll mentioned this pull request Dec 26, 2025

Roll Flutter from 6ff7f300473f to 096892ed81e8 (18 revisions) flutter/packages#10685

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 26, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

c5f61d7

…9676)

engine-flutter-autoroll mentioned this pull request Dec 26, 2025

Roll Flutter from 6ff7f300473f to 9ef3835ff659 (19 revisions) flutter/packages#10686

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 27, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

73d9347

…9676)

engine-flutter-autoroll mentioned this pull request Dec 27, 2025

Roll Flutter from 6ff7f300473f to 8455b1576e2b (28 revisions) flutter/packages#10687

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 27, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

68d107b

…9676)

engine-flutter-autoroll mentioned this pull request Dec 27, 2025

Roll Flutter from 6ff7f300473f to 8455b1576e2b (28 revisions) flutter/packages#10689

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 28, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

24e2ad6

…9676)

engine-flutter-autoroll mentioned this pull request Dec 28, 2025

Roll Flutter from 6ff7f300473f to c637545f6e5b (31 revisions) flutter/packages#10690

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 28, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

939be54

…9676)

engine-flutter-autoroll mentioned this pull request Dec 28, 2025

Roll Flutter from 6ff7f300473f to c637545f6e5b (31 revisions) flutter/packages#10691

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Dec 29, 2025

efce5d7 docs: clarify dropdown menu text clearing (flutter/flutter#17…

3f24d59

…9676)

engine-flutter-autoroll mentioned this pull request Dec 29, 2025

Roll Flutter from 6ff7f300473f to 60d8165b11e2 (32 revisions) flutter/packages#10694

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: clarify dropdown menu text clearing #179676

docs: clarify dropdown menu text clearing #179676

kazbeksultanov commented Dec 10, 2025 •

edited

Loading

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

QuncCccccc left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kazbeksultanov commented Dec 19, 2025

Uh oh!

kazbeksultanov commented Dec 22, 2025

Uh oh!

kazbeksultanov commented Dec 22, 2025

Uh oh!

QuncCccccc left a comment

Uh oh!

Uh oh!

Uh oh!

loic-sharma left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

docs: clarify dropdown menu text clearing #179676

docs: clarify dropdown menu text clearing #179676

Conversation

kazbeksultanov commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

packages/flutter/lib/src/material/dropdown_menu.dart (401-406)

Uh oh!

QuncCccccc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kazbeksultanov commented Dec 19, 2025

Uh oh!

kazbeksultanov commented Dec 22, 2025

Uh oh!

kazbeksultanov commented Dec 22, 2025

Uh oh!

QuncCccccc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

loic-sharma left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kazbeksultanov commented Dec 10, 2025 •

edited

Loading