Simple and robust Dropdown with item search feature

  Dropdown

Flutter DropdownSearch

Flutter simple and robust DropdownSearch with item search feature, making it possible to use an offline item list or filtering URL for easy customization.

Dropdown search

Key Features

  • Online and offline items
  • Searchable dropdown
  • Three dropdown mode: Menu/ BottomSheet/ Dialog
  • Material dropdown
  • Easy customizable UI
  • Handle Light and Dark theme
  • Easy implementation into statelessWidget

packages.yaml

dropdown_search: <lastest version>

Import

import 'package:dropdown_search/dropdown_search.dart';

Simple implementation

DropdownSearch<String>(
    mode: Mode.MENU,
    showSelectedItem: true,
    items: ["Brazil", "Italia (Disabled)", "Tunisia", 'Canada'],
    label: "Menu mode",
    hint: "country in menu mode",
    popupItemDisabled: (String s) => s.startsWith('I'),
    onChanged: print,
    selectedItem: "Brazil"),

customize showed field (itemAsString)

DropdownSearch<UserModel>(
  label: "Name",
  onFind: (String filter) => getData(filter),
  itemAsString: (UserModel u) => u.userAsStringByName(),
  onChanged: (UserModel data) => print(data),
),

DropdownSearch<UserModel>(
  label: "Name",
  onFind: (String filter) => getData(filter),
  itemAsString: (UserModel u) => u.userAsStringById(),
  onChanged: (UserModel data) => print(data),
),

customize Filter Function

DropdownSearch<UserModel>(
  label: "Name",
  filterFn: (user, filter) => user.userFilterByCreationDate(filter),
  onFind: (String filter) => getData(filter),
  itemAsString: (UserModel u) => u.userAsStringByName(),
  onChanged: (UserModel data) => print(data),
),

customize Search Mode

DropdownSearch<UserModel>(
  mode: Mode.BOTTOM_SHEET,
  label: "Name",
  onFind: (String filter) => getData(filter),
  itemAsString: (UserModel u) => u.userAsString(),
  onChanged: (UserModel data) => print(data),
),

Validation

DropdownSearch(
  items: ["Brazil", "France", "Tunisia", "Canada"],
  label: "Country",
  onChanged: print,
  selectedItem: "Tunisia",
  validator: (String item) {
    if (item == null)
      return "Required field";
    else if (item == "Brazil")
      return "Invalid item";
    else
      return null;
  },
);

Endpoint implementation (using Dio package)

DropdownSearch<UserModel>(
  label: "Name",
  onFind: (String filter) async {
    var response = await Dio().get(
        "http://5d85ccfb1e61af001471bf60.mockapi.io/user",
        queryParameters: {"filter": filter},
    );
    var models = UserModel.fromJsonList(response.data);
    return models;
  },
  onChanged: (UserModel data) {
    print(data);
  },
);

Layout customization

You can customize the layout of the DropdownSearch and its items. EXAMPLE

PropertiesDescription
labelDropDownSearch label
showSearchBoxshow/hide the search box
isFilteredOnlinetrue if the filter on items is applied onlie (via API)
showClearButtonshow/hide clear selected item
itemsoffline items list
selectedItemselected item
onFindfunction that returns item from API
onChangedcalled when a new item is selected
dropdownBuilderto customize list of items UI
popupItemBuilderto customize selected item
validatorfunction to apply the validation formula
searchBoxDecorationdecoration for the search box
popupBackgroundColorbackground color for the dialog/menu/bottomSheet
popupTitleCustom widget for the popup title
itemAsStringcustomize the fields the be shown
filterFncustom filter function
enabledenable/disable dropdownSearch
modeMENU / DIALOG/ BOTTOM_SHEET
maxHeightthe max height for dialog/bottomSheet/Menu
dialogMaxWidththe max width for the dialog
showSelectedItemmanage selected item visibility (if true, the selected item will be highlighted)
compareFnFunction(T item, T selectedItem), custom comparing function
dropdownSearchDecorationDropdownSearch input decoration
emptyBuildercustom layout for empty results
loadingBuildercustom layout for loading items
errorBuildercustom layout for error
autoFocusSearchBoxthe search box will be focused if true
popupShapecustom shape for the popup
autoValidateModehandle auto validation mode
onSavedAn optional method to call with the final value when the form is saved via
validatorAn optional method that validates an input. Returns an error string to display if the input is invalid, or null otherwise.
clearButtoncustomize clear button widget
dropDownButtoncustomize dropdown button widget
dropdownBuilderSupportsNullItemIf true, the dropdownBuilder will continue the uses of material behavior. This will be useful if you want to handle a custom UI only if the item !=null
popupItemDisableddefines if an item of the popup is enabled or not, if the item is disabled, it cannot be clicked
popupBarrierColorset a custom color for the popup barrier
searchBoxControllersearch box controller
clearButtonBuildercustom clear button builder
dropdownButtonBuildercustom dropdown button builder
onBeforeChangecallback executed before applying value change
searchDelaydelay before searching

Attention

To use a template as an item type, and you don’t want to use a custom fonction itemAsString and compareFn you need to implement toStringequals and hashcode, as shown below:

class UserModel {
  final String id;
  final DateTime createdAt;
  final String name;
  final String avatar;

  UserModel({this.id, this.createdAt, this.name, this.avatar});

  factory UserModel.fromJson(Map<String, dynamic> json) {
    if (json == null) return null;
    return UserModel(
      id: json["id"],
      createdAt:
          json["createdAt"] == null ? null : DateTime.parse(json["createdAt"]),
      name: json["name"],
      avatar: json["avatar"],
    );
  }

  static List<UserModel> fromJsonList(List list) {
    if (list == null) return null;
    return list.map((item) => UserModel.fromJson(item)).toList();
  }

  ///this method will prevent the override of toString
  String userAsString() {
    return '#${this.id} ${this.name}';
  }

  ///this method will prevent the override of toString
  bool userFilterByCreationDate(String filter) {
    return this?.createdAt?.toString()?.contains(filter);
  }

  ///custom comparing function to check if two users are equal
  bool isEqual(UserModel model) {
    return this?.id == model?.id;
  }

  @override
  String toString() => name;
}

Download Flutter DropdownSearch source code on GitHub

https://github.com/salim-lachdhaf/searchable_dropdown