Friday, December 1, 2023

Simple and robust FindDropdown with item search feature

Dropdown search

Key Features

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


dropdown_search: <lastest version>


import 'package:dropdown_search/dropdownSearch.dart';

Simple implementation

    mode: Mode.MENU,
    showSelectedItem: true,
    items: ["Brazil", "Italia", "Tunisia", 'Canada'],
    label: "Menu mode",
    hint: "country in menu mode",
    onChanged: print,
    selectedItem: "Brazil"),

customize showed field (itemAsString)

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

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

customize Filter Function

  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

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


  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";
      return null;

Endpoint implementation (using Dio package)

  label: "Name",
  onFind: (String filter) async {
    var response = await Dio().get(
        queryParameters: {"filter": filter},
    var models = UserModel.fromJsonList(;
    return models;
  onChanged: (UserModel data) {

Layout customization

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

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
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
autoValidatehandle auto validation
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


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.createdAt,, this.avatar});

  factory UserModel.fromJson(Map<String, dynamic> json) {
    if (json == null) return null;
    return UserModel(
      id: json["id"],
          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 => UserModel.fromJson(item)).toList();

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

  ///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;

  String toString() => name;