Flutter DropdownSearch

This is a fork of original DropdownSearch. Sometimes it takes weeks between merging PR and release so I deciced to make my own. I'm tying to keep in sync and contribute to main repo.

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


Key FeaturesExamplesLicense

Dropdown search

Key Features

  • Sync and/or Async items (online, offline, DB, ...)
  • Searchable dropdown
  • Three dropdown mode: Menu/ BottomSheet/ Dialog
  • Single & multi selection
  • Material dropdown
  • Easy customizable UI
  • Handle Light and Dark theme
  • Easy implementation into statelessWidget


dropdown_search: <lastest version>


import 'package:dropdown_search/dropdown_search.dart';

Simple implementation

    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"),
    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,
    selectedItems: ["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(response.data);
    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
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
clearButtonSplashRadiuscustomize clear button splash radius
dropDownButtoncustomize dropdown button widget
dropDownButtonSplashRadiuscustomize dropdown button splash radius
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
popupSafeAreaset properties of popup safe area
scrollbarPropsscrollbar properties
popupBarrierDismissiblewhether modal can be dismissed by tapping the modal barrier
selectionListViewPropsprops for selection list view


To use a template as an item type, and you don't want to use a custom function itemAsString and compareFn you need to implement toString, equals 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"],
          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;

  String toString() => name;

View more Examples


If this plugin was useful to you, helped you to deliver your app, saved you a lot of time, or you just want to support the project, I would be very grateful if you buy me a cup of coffee.

Buy Me A Coffee