initialSelection property

T? initialSelection
final

The value used for an initial selection.

This property sets the initial value of the dropdown menu when the widget is first created. If the value matches one of the dropdownMenuEntries, the corresponding label will be displayed in the text field.

Setting this to null on a rebuild does not clear the text field, because DropdownMenu only updates the text field when initialSelection changes to a value that matches one of the dropdownMenuEntries.

To programmatically clear or reset the selection, provide a controller and call TextEditingController.clear on it alongside resetting the state variable to null.

Defaults to null.

This sample demonstrates how to programmatically clear the selection in a DropdownMenu using a TextEditingController.

To see it in action, copy and run this code snippet on DartPad.

import 'package:material_ui/material_ui.dart';

/// Flutter code sample for [DropdownMenu] showing how to programmatically
/// clear or reset the selection using a [TextEditingController].

void main() => runApp(const DropdownMenuClearExampleApp());

class DropdownMenuClearExampleApp extends StatelessWidget {
  const DropdownMenuClearExampleApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Clear DropdownMenu Sample')),
        body: const Center(child: DropdownMenuClearExample()),
      ),
    );
  }
}

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

  @override
  State<DropdownMenuClearExample> createState() =>
      _DropdownMenuClearExampleState();
}

enum ColorItem {
  red('Red'),
  green('Green'),
  blue('Blue');

  const ColorItem(this.label);
  final String label;
}

class _DropdownMenuClearExampleState extends State<DropdownMenuClearExample> {
  final TextEditingController _controller = TextEditingController();
  ColorItem? _selectedColor = ColorItem.red;

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  void _clearSelection() {
    setState(() {
      _selectedColor = null;
      _controller.clear();
    });
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: <Widget>[
        DropdownMenu<ColorItem>(
          controller: _controller,
          initialSelection: _selectedColor,
          label: const Text('Color'),
          onSelected: (ColorItem? color) {
            setState(() {
              _selectedColor = color;
            });
          },
          dropdownMenuEntries: ColorItem.values
              .map<DropdownMenuEntry<ColorItem>>((ColorItem color) {
                return DropdownMenuEntry<ColorItem>(
                  value: color,
                  label: color.label,
                );
              })
              .toList(),
        ),
        const SizedBox(height: 20),
        FilledButton(
          onPressed: _clearSelection,
          child: const Text('Clear selection'),
        ),
        const SizedBox(height: 20),
        Text('Selected: ${_selectedColor?.label ?? 'None'}'),
      ],
    );
  }
}

See also:

  • controller, which is required to programmatically clear or modify the text field content.

Implementation

// TODO(framework): Replace the following block with a @dartpad directive
// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
/// {@macro material_ui.dartpad_guide}
///
/// {@example /example/lib/dropdown_menu/dropdown_menu.3.dart#body}
///
/// </callout-box>
///
/// See also:
///
///  * [controller], which is required to programmatically clear or modify
///    the text field content.
final T? initialSelection;