🧮 MultiDataPicker #

multi_data_picker is a customizable multi-select widget for Flutter, inspired by the UX of Select2 and architecturally based on the any_field pattern. It allows users to select multiple values from dynamic data sources with support for generic types, popup customization (dialog, page, bottom), and external state control via MultiPickerController.

Designed to integrate seamlessly into form layouts, it supports full TextField styling via InputDecoration, making it visually consistent with standard Flutter input fields. Ideal for filter panels, tag selectors, and data-driven workflows.

✨ 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 #

📦 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'] ?? "-",
    ),
  ),
)

🧱 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.

Example:

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.

Example:

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.

🧾 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 #

🤝 Contributing #

We welcome contributions! Feel free to open issues, submit pull requests, or suggest improvements.

git clone https://github.com/your-org/multi_data_picker.git

☕ Support This Project #

If you find multi_data_picker helpful, consider supporting its development:

📄 License #

MIT License - see the LICENSE file for details