🧮 MultiDataPicker #

multi_data_picker is a customizable multi-select widget for Flutter, inspired by Select2. It supports dynamic data, generic types, popup customization (dialog, page, bottom), and external control via MultiPickerController.

Designed for seamless form integration with full InputDecoration styling—ideal for filters, tag selectors, and data-driven UIs.

🤝 How to Contribute #

Before diving into the docs, here’s how you can support the plugin:

• 🐞 Found a bug or have an idea?
  Open an issue on GitHub

• 🔧 Got time to fix it?
  Fork the repo and submit a pull request—we’ll review it fast

• 💖 Want to support the project?
  If this plugin makes your life easier, a small donation helps us keep building and improving it for everyone

  

• 👍 Like what you see?
  Smash the thumbs-up on pub.flutter-io.cn—it helps more devs discover us!

📘 Table of Contents #

• 🧮 MultiDataPicker
  • 🤝 How to Contribute
  • 📘 Table of Contents
  • ✨ Features
  • 📸 Demo
  • 📦 Installation
  • 🚀 Usage
    • 🧩 Notes on AnyField Integration
  • 🧱 Constructor Parameters
  • 🧩 Display Builder
    • 1. DataDisplayBuilder.string
    • 2. DataDisplayBuilder.custom
  • 🪟 Popup Types
    • 1. dialog
    • 2. page
    • 3. bottom
    • 🪟 Popup Type Parameters
  • 🔄 Handling Data Loading & Infinite Scroll
    • 🧠 Parameters
    • ✅ Returning Data
    • ❌ Returning Error
    • 🔁 Infinite Scroll Behavior
    • 🧪 Example
  • 🧾 List Data Builder
    • 1. ListDataBuilder.string
    • 2. ListDataBuilder.custom
    • 🧾 ListDataBuilder Parameters
    • 🧾 ListTileMetadata
  • 🎮 MultiPickerController
    • Example
    • 🎮 Controller API
  • 📄 License

✨ Features #

• ✅ Generic support for any data type T
• 🧱 Custom display builder (text or widget)
• 🪟 Popup picker: dialog, page, or bottom
• 🎛️ Controller support for external state management
• 🧩 TextField-style appearance via InputDecoration
• 🔄 Initial value and change detection hooks
• 📐 Layout, spacing, and tile styling options

📸 Demo #

Fix Height	Dialog Picker	Page Picker

Bottom Picker	Custom	With Controller

📦 Installation #

Add this to your pubspec.yaml:

dependencies:
  multi_data_picker: ^<latest_version>

Then run:

flutter pub get

🚀 Usage #

MultiDataPicker<Map<String, dynamic>>(
  initialValue: [data[0], data[1]],
  isEqual: (a, b) => a["id"] == b["id"],
  decoration: InputDecoration(
    labelText: "Input Label",
    prefixIcon: Icon(Icons.location_city),
    border: OutlineInputBorder(
      borderRadius: BorderRadius.circular(5),
    ),
  ),
  minHeight: 100,
  maxHeight: 150,
  dataDisplayBuilder: DataDisplayBuilder.string(
    labelBuilder: (data) => data['name'] ?? "-",
  ),
  popupType: DataPickerPopupType.bottom(
    loadData: loadData,
    listDataBuilder: ListDataBuilder.string(
      labelBuilder: (data) => data['name'] ?? "-",
    ),
  ),
)

🧩 Notes on AnyField Integration #

multi_data_picker is built on top of any_field, which provides the core layout and interaction model. As a result, it inherits several important behaviors:

isDense is always true

To maintain compact vertical spacing, AnyField sets InputDecoration.isDense = true by default. This affects how icons and padding are rendered.

• If you use prefixIcon or suffixIcon, explicitly set their size to 24.0 to match the default TextField appearance:

InputDecoration(
  labelText: 'Tags',
  suffixIcon: Icon(Icons.tag, size: 24), // Match native TextField alignment
)

🧱 Constructor Parameters #

🧩 Display Builder #

The DataDisplayBuilder<T> sealed class defines how each selected item is rendered inside the picker. It supports two modes:

1. DataDisplayBuilder.string #

Renders each item as a Chip with customizable appearance.

DataDisplayBuilder.string(
  labelBuilder: (data) => data['name'] ?? "-",
  backgroundColor: Colors.blue.shade50,
  labelStyle: TextStyle(fontWeight: FontWeight.bold),
  shape: StadiumBorder(),
  deleteIconColor: Colors.red,
  deleteIcon: Icon(Icons.close),
  avatar: CircleAvatar(child: Text("A")),
  avatarBoxConstraints: BoxConstraints.tight(Size(24, 24)),
  labelPadding: EdgeInsets.symmetric(horizontal: 8),
  side: BorderSide(color: Colors.grey),
)

2. DataDisplayBuilder.custom #

Provides full control over rendering via a custom widget builder.

DataDisplayBuilder.custom(
  builder: (context, data, delete) {
    return Row(
      children: [
        Text(data['name']),
        IconButton(
          icon: Icon(Icons.delete),
          onPressed: delete,
        ),
      ],
    );
  },
)

Use this when you need advanced layout or interactivity beyond the default Chip UI.

🪟 Popup Types #

The popupType parameter defines how the selection UI is presented. It uses a sealed class DataPickerPopupType<T> with three variants:

1. dialog #

Displays a modal dialog with optional title, search input, and action buttons.

DataPickerPopupType.dialog(
  loadData: loadData,
  listDataBuilder: ListDataBuilder.string(
    labelBuilder: (data) => data['name'] ?? "-",
  ),
  titleText: "Dialog Title",
)

2. page #

Displays a full-screen modal page.

DataPickerPopupType.page(
  loadData: loadData,
  listDataBuilder: ListDataBuilder.string(
    labelBuilder: (data) => data['name'] ?? "-",
  ),
  titleText: 'Choose Options',
  withCancelButton: true,
)

3. bottom #

Shows a bottom sheet for quick, contextual selection.

DataPickerPopupType.bottom(
  loadData: loadData,
  listDataBuilder: ListDataBuilder.string(
    labelBuilder: (data) => data['name'] ?? "-",
  ),
  titleText: 'Choose Options',
  withCancelButton: true,
)

🪟 Popup Type Parameters #

Notes:

• searchAutoFocus defaults to false for dialog and bottom, and true for page.
• withCancelButton defaults to false for both page and bottom.
• width is only available in dialog; height is available in dialog and bottom.

🔄 Handling Data Loading & Infinite Scroll #

To load data dynamically in multi_data_picker, you must provide a loadData callback of type:

typedef ListDataPickerCallback<T> = FutureOr<ListDataPicker<T>> Function(String filter, List<T> previous);

This callback is triggered whenever the picker needs to fetch new data — either on initial load or during infinite scroll.

🧠 Parameters #

• filter: A string used to filter the data (e.g. search query).
• previous: The list of previously loaded items, useful for pagination or deduplication.

✅ Returning Data #

To return a successful result, use:

return ListDataPicker.data(
  fetchedItems,
  hasNext: true, // or false if no more data
);

• fetchedItems: A list of items of type T.
• hasNext: Set to true if more data is available (enables infinite scroll). Set to false to stop loading.

❌ Returning Error #

If something goes wrong (e.g. network error, invalid response), return:

return ListDataPicker.error("Failed to load data");

This will display an error state in the picker UI.

🔁 Infinite Scroll Behavior #

When hasNext is true, the picker will automatically trigger loadData again when the user scrolls to the bottom. This allows seamless infinite scrolling with paginated data.

🧪 Example #

Future<ListDataPicker<User>> loadUsers(String filter, List<User> previous) async {
  try {
    final response = await api.fetchUsers(filter, offset: previous.length);
    return ListDataPicker.data(response.items, hasNext: response.hasMore);
  } catch (e) {
    return ListDataPicker.error("Unable to load users");
  }
}

🧾 List Data Builder #

The ListDataBuilder<T> sealed class defines how each item in the popup selection list is rendered. It supports two modes:

1. ListDataBuilder.string #

Displays each item as a simple text-based ListTile.

ListDataBuilder.string(
  labelBuilder: (data) => data['name'] ?? "-",
)

2. ListDataBuilder.custom #

Provides full control over rendering via a custom widget builder.

ListDataBuilder.custom(
  builder: (context, data, metadata) {
    return Container(
      color: metadata.selected ? Colors.green.shade100 : null,
      child: Row(
        children: [
          Text(data['name']),
          if (metadata.isEven) Icon(Icons.star),
        ],
      ),
    );
  },
)

🧾 ListDataBuilder Parameters #

🧾 ListTileMetadata #

This helper class provides metadata for each item in the list:

Use this metadata inside ListDataBuilder.custom to style or annotate items dynamically.

🎮 MultiPickerController #

MultiPickerController<T> is an optional controller that allows external control over the selected values in MultiDataPicker. It enables programmatic selection, deselection, toggling, and clearing of items, and notifies listeners when changes occur.

Example #

final controller = MultiPickerController<Map<String, dynamic>>(
  isEquals: (a, b) => a['id'] == b['id'],
  initialValue: [data[0]],
);

MultiDataPicker<Map<String, dynamic>>(
  controller: controller,
  isEqual: controller.isEquals,
  // other parameters...
);

🎮 Controller API #

📄 License #

MIT License - see the LICENSE file for details