The perfect selection
for your premium app.

A developer-friendly Flutter package for intuitive multi-selection. Whether you are a beginner or a pro, building beautiful interfaces is now effortless.

Beginner Friendly

Clean API, detailed documentation, and simple implementation patterns.

Premium UI

Tailored for high-end applications with a focus on visual excellence.

Step-by-Step Tutorial 🚀

Let's build your first multi-selector in 4 easy steps.

Add the Dependency

Open your pubspec.yaml and add the package manually or via CLI.

dependencies:
  flutter_multi_selector: ^latest

Tip: Run flutter pub get to finalize the installation.

Wrap Your Items

The library uses MultiSelectorItem to handle labels and values. It is generic, so you can use any data type.

// Simple string list
final items = ["Red", "Green", "Blue"]
    .map((c) => MultiSelectorItem(c, c))
    .toList();

Display the Widget

Place the selector in your UI. Use DialogField for focus or BottomSheetField for a modern feel.

MultiSelectorDialogField<String>(
  items: items,
  onConfirm: (values) => print(values),
)

Handle the Result

Use the onConfirm callback to capture the selected values and update your app state.

onConfirm: (List<String> selected) {
  setState(() => _mySelection = selected);
}

Dialog Field Guide 💬

Place the selector in your UI. Use DialogField for focus or BottomSheetField for a modern feel.

MultiSelectorDialogField<String>(
  items: items,
  onConfirm: (values) => print(values),
)

BottomSheet Field Guide 📱

An elegant, native-feeling mobile interaction. Perfect for quick selections.

MultiSelectorBottomSheetField<String>(
  items: items,
  searchable: true,
  onConfirm: (values) => print(values),
)

Deep Dive into Data 📊

One of the most powerful features is the generic MultiSelectorItem<T>. It allows you to use your own custom objects directly as values.

Using Custom Objects

class User {
  final int id;
  final String name;
  User(this.id, this.name);
}

// Convert users to items
final userItems = users.map((u) => MultiSelectorItem(u, u.name)).toList();

// Now 'values' will be a List<User>
MultiSelectorDialogField<User>(
  items: userItems,
  onConfirm: (values) => print(values[0].id),
)

Validation Guide 🛠

Need to force a selection? Use the validator property within a Form.

MultiSelectorBottomSheetField<String>(
  items: items,
  validator: (selected) {
    if (selected == null || selected.isEmpty) {
      return "Please select at least one item!";
    }
    return null; // All good!
  },
  autovalidateMode: AutovalidateMode.onUserInteraction,
  onConfirm: (values) => print(values),
)

The Look

Dialog List View

BottomSheet Chip Grid

Changelog 📝

Stay up to date with the latest features and improvements.

v1.2.0+1 (Current)

Released on March 25, 2026

✨ Complete Redesign: Premium Isar-inspired aesthetic applied across docs.
🐣 Beginner Friendly: Added "Your First Widget" guide and 4-step tutorial.
📊 Data Modeling: Detailed guides on using custom objects with `MultiSelectorItem`.
📱 Fully Responsive: Mobile-optimized navigation drawer and fluid layouts.
🔍 API clarity: Simplified and expanded documentation for all parameters.

View Full History →

Common Questions (FAQ) ❓

Can I use custom colors?

Absolutely! Use selectedColor, checkColor, and backgroundColor to match your brand.

Does it support search?

Yes. Just set searchable: true to enable a high-performance search bar.

How do I pre-select items?

Pass your initial list of values to the initialValue parameter.

API Quick Reference

Parameter	Beginner Explanation
`items`	A list of everything the user can choose from.
`onConfirm`	The function that runs after the user clicks "Finish".
`title`	The text or icon shown at the top of the selection view.
`searchable`	Turn this on to let users filter the list.
`showSelectAll`	Adds a button to select or clear everything at once.

The perfect selection for your premium app.