Skip to content

Commit b204a50

Browse files
docs: clarify programmatic clearing for DropdownMenu and add code sample
- Updates documentation for DropdownMenu.controller and initialSelection to explain how to programmatically clear the selection using TextEditingController.clear(). - Adds an API example and widget tests demonstrating the clear pattern. Fixes flutter#177599
1 parent 84d209d commit b204a50

3 files changed

Lines changed: 187 additions & 3 deletions

File tree

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
// Copyright 2014 The Flutter Authors. All rights reserved.
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:flutter/material.dart';
6+
7+
/// Flutter code sample for [DropdownMenu] showing how to programmatically
8+
/// clear or reset the selection using a [TextEditingController].
9+
10+
void main() => runApp(const DropdownMenuClearExampleApp());
11+
12+
class DropdownMenuClearExampleApp extends StatelessWidget {
13+
const DropdownMenuClearExampleApp({super.key});
14+
15+
@override
16+
Widget build(BuildContext context) {
17+
return MaterialApp(
18+
home: Scaffold(
19+
appBar: AppBar(title: const Text('Clear DropdownMenu Sample')),
20+
body: const Center(child: DropdownMenuClearExample()),
21+
),
22+
);
23+
}
24+
}
25+
26+
class DropdownMenuClearExample extends StatefulWidget {
27+
const DropdownMenuClearExample({super.key});
28+
29+
@override
30+
State<DropdownMenuClearExample> createState() =>
31+
_DropdownMenuClearExampleState();
32+
}
33+
34+
enum ColorItem {
35+
red('Red'),
36+
green('Green'),
37+
blue('Blue');
38+
39+
const ColorItem(this.label);
40+
final String label;
41+
}
42+
43+
class _DropdownMenuClearExampleState extends State<DropdownMenuClearExample> {
44+
final TextEditingController _controller = TextEditingController();
45+
ColorItem? _selectedColor;
46+
47+
@override
48+
void dispose() {
49+
_controller.dispose();
50+
super.dispose();
51+
}
52+
53+
void _clearSelection() {
54+
setState(() {
55+
_selectedColor = null;
56+
_controller.clear();
57+
});
58+
}
59+
60+
@override
61+
Widget build(BuildContext context) {
62+
return Column(
63+
mainAxisAlignment: MainAxisAlignment.center,
64+
children: <Widget>[
65+
DropdownMenu<ColorItem>(
66+
controller: _controller,
67+
initialSelection: _selectedColor,
68+
label: const Text('Color'),
69+
onSelected: (ColorItem? color) {
70+
setState(() {
71+
_selectedColor = color;
72+
});
73+
},
74+
dropdownMenuEntries: ColorItem.values
75+
.map<DropdownMenuEntry<ColorItem>>((ColorItem color) {
76+
return DropdownMenuEntry<ColorItem>(
77+
value: color,
78+
label: color.label,
79+
);
80+
})
81+
.toList(),
82+
),
83+
const SizedBox(height: 20),
84+
FilledButton(
85+
onPressed: _clearSelection,
86+
child: const Text('Clear selection'),
87+
),
88+
const SizedBox(height: 20),
89+
Text('Selected: ${_selectedColor?.label ?? 'None'}'),
90+
],
91+
);
92+
}
93+
}
Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
// Copyright 2014 The Flutter Authors. All rights reserved.
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:flutter/material.dart';
6+
import 'package:flutter_api_samples/material/dropdown_menu/dropdown_menu.3.dart'
7+
as example;
8+
import 'package:flutter_test/flutter_test.dart';
9+
10+
void main() {
11+
testWidgets('Selecting an entry updates the text field and state', (
12+
WidgetTester tester,
13+
) async {
14+
await tester.pumpWidget(const example.DropdownMenuClearExampleApp());
15+
16+
expect(find.text('Selected: None'), findsOne);
17+
expect(find.widgetWithText(TextField, ''), findsOne);
18+
19+
// Open menu and select Green.
20+
await tester.tap(find.byType(DropdownMenu<example.ColorItem>));
21+
await tester.pumpAndSettle();
22+
23+
await tester.tap(find.widgetWithText(MenuItemButton, 'Green').last);
24+
await tester.pumpAndSettle();
25+
26+
expect(find.text('Selected: Green'), findsOne);
27+
expect(find.widgetWithText(TextField, 'Green'), findsOne);
28+
});
29+
30+
testWidgets(
31+
'Pressing clear selection button resets the text field and state',
32+
(WidgetTester tester) async {
33+
await tester.pumpWidget(const example.DropdownMenuClearExampleApp());
34+
35+
// Open menu and select Blue.
36+
await tester.tap(find.byType(DropdownMenu<example.ColorItem>));
37+
await tester.pumpAndSettle();
38+
39+
await tester.tap(find.widgetWithText(MenuItemButton, 'Blue').last);
40+
await tester.pumpAndSettle();
41+
42+
expect(find.text('Selected: Blue'), findsOne);
43+
expect(find.widgetWithText(TextField, 'Blue'), findsOne);
44+
45+
// Tap clear button.
46+
await tester.tap(find.widgetWithText(FilledButton, 'Clear selection'));
47+
await tester.pumpAndSettle();
48+
49+
expect(find.text('Selected: None'), findsOne);
50+
expect(find.widgetWithText(TextField, ''), findsOne);
51+
},
52+
);
53+
}

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

Lines changed: 41 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,13 @@ enum DropdownMenuCloseBehavior {
171171
/// ** See code in examples/api/lib/material/dropdown_menu/dropdown_menu.0.dart **
172172
/// {@end-tool}
173173
///
174+
/// {@tool dartpad}
175+
/// This sample demonstrates how to programmatically clear or reset the selection
176+
/// in a [DropdownMenu] using a [TextEditingController].
177+
///
178+
/// ** See code in examples/api/lib/material/dropdown_menu/dropdown_menu.3.dart **
179+
/// {@end-tool}
180+
///
174181
/// See also:
175182
///
176183
/// * [MenuAnchor], which is a widget used to mark the "anchor" for a set of submenus.
@@ -430,6 +437,27 @@ class DropdownMenu<T> extends StatefulWidget {
430437
/// Controls the text being edited or selected in the menu.
431438
///
432439
/// If null, this widget will create its own [TextEditingController].
440+
///
441+
/// A [TextEditingController] can be provided to programmatically clear or modify
442+
/// the displayed selection. For example, calling [TextEditingController.clear]
443+
/// clears the text displayed in the dropdown menu.
444+
///
445+
/// When tracking the selected value in a state variable, calling
446+
/// [TextEditingController.clear] alongside updating the state variable to null
447+
/// is required to clear the displayed selection, as updating [initialSelection]
448+
/// does not clear the text field.
449+
///
450+
/// {@tool dartpad}
451+
/// This sample demonstrates how to programmatically clear the selection in a
452+
/// [DropdownMenu] using a [TextEditingController].
453+
///
454+
/// ** See code in examples/api/lib/material/dropdown_menu/dropdown_menu.3.dart **
455+
/// {@end-tool}
456+
///
457+
/// See also:
458+
///
459+
/// * [initialSelection], which sets the initial selection when the widget is
460+
/// first created.
433461
final TextEditingController? controller;
434462

435463
/// The value used for an initial selection.
@@ -438,13 +466,23 @@ class DropdownMenu<T> extends StatefulWidget {
438466
/// is first created. If the value matches one of the [dropdownMenuEntries],
439467
/// the corresponding label will be displayed in the text field.
440468
///
441-
/// Setting this to null does not clear the text field.
469+
/// Setting this to null does not clear the text field because [initialSelection]
470+
/// only specifies an initial selection and does not act as a reactive, controlled
471+
/// selection property.
442472
///
443-
/// To programmatically clear the text field, use a [TextEditingController]
444-
/// and call [TextEditingController.clear] on it.
473+
/// To programmatically clear or reset the selection, provide a [controller]
474+
/// and call [TextEditingController.clear] on it alongside resetting the state
475+
/// variable to null.
445476
///
446477
/// Defaults to null.
447478
///
479+
/// {@tool dartpad}
480+
/// This sample demonstrates how to programmatically clear the selection in a
481+
/// [DropdownMenu] using a [TextEditingController].
482+
///
483+
/// ** See code in examples/api/lib/material/dropdown_menu/dropdown_menu.3.dart **
484+
/// {@end-tool}
485+
///
448486
/// See also:
449487
///
450488
/// * [controller], which is required to programmatically clear or modify

0 commit comments

Comments
 (0)