MultiSelect Dropdown

A powerful and highly customizable multi-select dropdown widget for Flutter. Supports single & multi-select, search, form validation, programmatic control, and extensive visual customization.

Preview

Features

• ✅ Multi-select & single-select modes
• ✅ Searchable dropdown with customizable search field
• ✅ Form validation support with autovalidateMode
• ✅ Programmatic control via MultiSelectController
• ✅ Async data loading with MultiDropdown.future()
• ✅ Extensive decoration classes (chips, field, dropdown, items, search)
• ✅ Pre-selected & disabled items
• ✅ Max selection limit with maxSelections
• ✅ Chip overflow control with maxDisplayCount
• ✅ Custom item builders & selected item builders
• ✅ Header & footer widgets in the dropdown
• ✅ Expand direction control (auto, up, down)
• ✅ Close on back button support
• ✅ Full InputDecoration override for form consistency
• ✅ Grouped items with customizable section headers
• ✅ Select All / Deselect All toggle with customizable labels
• ✅ Custom search filter for fuzzy matching and multi-field search
• ✅ Bottom sheet mode for mobile-friendly item selection

Installation

Add to your pubspec.yaml:

dependencies:
  multi_dropdown: ^3.2.1

Quick Start

Basic Multi-Select

MultiDropdown<String>(
  items: [
    DropdownItem(label: 'Australia', value: 'AU'),
    DropdownItem(label: 'Canada', value: 'CA'),
    DropdownItem(label: 'India', value: 'IN'),
    DropdownItem(label: 'United States', value: 'US'),
  ],
  onSelectionChange: (selectedItems) {
    debugPrint('Selected: $selectedItems');
  },
);

Single Select

MultiDropdown<String>(
  items: items,
  singleSelect: true,
  fieldDecoration: FieldDecoration(
    hintText: 'Choose a role',
    suffixIcon: const Icon(Icons.keyboard_arrow_down_rounded),
  ),
  onSelectionChange: (values) {
    debugPrint('Selected: ${values.first}');
  },
);

Searchable Dropdown

MultiDropdown<String>(
  items: items,
  searchEnabled: true,
  searchDecoration: SearchFieldDecoration(
    hintText: 'Type to search...',
  ),
);

With Form Validation

MultiDropdown<String>(
  items: items,
  maxSelections: 4,
  autovalidateMode: AutovalidateMode.onUserInteraction,
  validator: (selectedItems) {
    if (selectedItems == null || selectedItems.isEmpty) {
      return 'Please select at least one item';
    }
    return null;
  },
);

Async Data Loading

MultiDropdown<int>.future(
  future: () async {
    final response = await http.get(Uri.parse('https://api.example.com/users'));
    final data = jsonDecode(response.body) as List;
    return data.map((e) => DropdownItem(
      label: e['name'] as String,
      value: e['id'] as int,
    )).toList();
  },
);

Controller

Use MultiSelectController to programmatically control the dropdown:

final controller = MultiSelectController<String>();

controller.setItems(items);       // Set/replace items
controller.addItem(item);         // Add a single item
controller.addItems(items);       // Add multiple items

controller.selectAll();           // Select all items
controller.clearAll();            // Deselect all items
controller.selectAtIndex(0);      // Select item at index
controller.selectWhere((i) => i.value == 'dart');   // Select by predicate
controller.unselectWhere((i) => i.value == 'dart'); // Deselect by predicate
controller.toggleWhere((i) => i.value == 'dart');   // Toggle by predicate
controller.disableWhere((i) => i.value == 'admin'); // Disable by predicate

controller.openDropdown();        // Open the dropdown
controller.closeDropdown();       // Close the dropdown
controller.clearSearch();         // Clear search query

controller.items;                 // All items
controller.selectedItems;         // Selected items
controller.disabledItems;         // Disabled items
controller.isOpen;                // Dropdown open state

Examples

The example app contains 8 dedicated examples, each in its own file:

Run the example:

cd example
flutter run

API Reference

MultiDropdown

DropdownItem

ChipDecoration

FieldDecoration

DropdownDecoration

SearchFieldDecoration

DropdownItemDecoration

Migration from v2.x

See the CHANGELOG for details on breaking changes in v3.0.0.

Key changes:

• MultiSelectDropDown → MultiDropdown
• ValueItem → DropdownItem
• .network() → .future()
• onOptionsSelected → onSelectionChange

License

MIT License