multiselector 1.0.4
multiselector: ^1.0.4 copied to clipboard
Fast and lightweight universal item selector for Flutter with fuzzy search and customizable UI — lightweight and flexible.
multiselector #
Lightweight and blazing fast universal item selector for Flutter apps with fuzzy search and customizable UI — perfect for any list selection needs.
🌐 Live Demo: View on GitHub Pages
Features #
- Universal Selection - Works with any list of items: countries, languages, currencies, timezones, categories, products, users, settings, colors, emojis, tags, and any custom data you need to select from
- Multi-Select Support - Choose single or multiple items with configurable limits
- Smart Search - Find items by name, subtitle, or custom search data with fuzzy matching
- Customizable UI - Dark/light themes with custom colors and styling
- High Performance - Optimized search algorithm with fuzzy search support
- Responsive Design - Works perfectly on mobile, tablet, and desktop
- Easy Integration - Zero configuration required, works out of the box
- Flexible Data - Support for icons, subtitles, and custom search data
Performance #
- Package Size: ~50KB (lightweight, no translations)
- Search Speed: Fast fuzzy search with typos support
- Memory Usage: Optimized for weak devices
- Multi-Select: Efficient handling of multiple selections
- Flexible: Works with any data structure
Installation #
Add the dependency to your pubspec.yaml
:
dependencies:
multiselector: ^1.0.2
Usage #
Basic Usage #
Single Selection
import 'package:multiselector/multiselector.dart';
// Define your items
final List<SelectableItem> items = [
const SelectableItem(
id: 'apple',
name: 'Apple',
icon: '🍎',
subtitle: 'Red fruit',
searchData: 'apple fruit red sweet',
),
const SelectableItem(
id: 'banana',
name: 'Banana',
icon: '🍌',
subtitle: 'Yellow fruit',
searchData: 'banana fruit yellow potassium',
),
];
// Single selection
UniversalSelector(
items: items,
selectedItem: selectedItem,
onItemSelected: (SelectableItem item) {
setState(() {
selectedItem = item;
});
debugPrint('Selected: ${item.icon} ${item.name}');
},
)
Multi Selection
// Multi selection
List<SelectableItem> selectedItems = [];
UniversalSelector(
items: items,
selectedItems: selectedItems,
isMultiSelect: true,
onItemsSelected: (List<SelectableItem> items) {
setState(() {
selectedItems = items;
});
debugPrint('Selected ${items.length} items');
},
maxSelections: 3, // Optional: limit selections
)
API Reference #
UniversalSelector #
The main widget for item selection.
Properties
Property | Type | Default | Description |
---|---|---|---|
items |
List<SelectableItem> |
Required | List of items to display in the selector |
selectedItem |
SelectableItem? |
null |
Currently selected item. Pass null for no selection |
selectedItems |
List<SelectableItem> |
[] |
List of currently selected items for multi-select mode |
onItemSelected |
Function(SelectableItem) |
Required | Callback function triggered when user selects an item |
onItemsSelected |
Function(List<SelectableItem>)? |
null |
Callback function for multi-select mode |
isMultiSelect |
bool |
false |
Enable multi-select mode |
maxSelections |
int? |
null |
Maximum number of items that can be selected |
labelText |
String? |
'Select Item' |
Text displayed in the modal header |
hintText |
String? |
'Search items...' |
Placeholder text in the search field |
showSubtitle |
bool |
true |
Whether to display subtitles for items |
backgroundColor |
Color? |
Dark theme | Background color of the modal dialog |
headerColor |
Color? |
Dark theme | Background color of the modal header |
textColor |
Color? |
Dark theme | Primary text color for item names |
accentColor |
Color? |
Green | Color for accent elements (like selected items) |
searchFieldColor |
Color? |
Dark theme | Background color of the search input field |
searchFieldBorderColor |
Color? |
Dark theme | Border color of the search input field |
cursorColor |
Color? |
White | Color of the text cursor in the search field |
hintTextColor |
Color? |
Dark theme | Color of placeholder text in search field |
hoverColor |
Color? |
Dark theme | Background color when hovering over items |
borderRadius |
double? |
8.0 |
Border radius applied to all rounded elements |
SelectableItem #
Represents a selectable item with its properties.
Properties
Property | Type | Description |
---|---|---|
id |
String |
Unique identifier for the item |
name |
String |
Display name of the item |
icon |
String? |
Optional icon/emoji for the item |
subtitle |
String? |
Optional subtitle/description |
searchData |
String? |
Optional additional data for search |
data |
dynamic |
Optional custom data object |
Examples #
Countries Selection #
final List<SelectableItem> countries = [
const SelectableItem(
id: 'us',
name: 'United States',
icon: '🇺🇸',
subtitle: 'USA',
searchData: 'united states america us usa',
),
const SelectableItem(
id: 'ru',
name: 'Russia',
icon: '🇷🇺',
subtitle: 'Russian Federation',
searchData: 'russia russian federation',
),
];
UniversalSelector(
items: countries,
selectedItem: selectedCountry,
onItemSelected: (SelectableItem country) {
setState(() {
selectedCountry = country;
});
},
labelText: 'Choose a country',
hintText: 'Search countries...',
)
Custom Theme #
UniversalSelector(
items: items,
selectedItem: selectedItem,
onItemSelected: (SelectableItem item) {
setState(() {
selectedItem = item;
});
},
// Custom colors for light theme
backgroundColor: Colors.white,
headerColor: Colors.grey.shade100,
textColor: Colors.black87,
accentColor: Colors.blue,
searchFieldColor: Colors.grey.shade50,
searchFieldBorderColor: Colors.grey.shade300,
cursorColor: Colors.blue,
hintTextColor: Colors.grey.shade600,
hoverColor: Colors.grey.shade200,
borderRadius: 12.0,
labelText: 'Custom theme selector',
hintText: 'Search items...',
)
Multi-Select Mode #
List<SelectableItem> selectedItems = [];
UniversalSelector(
items: items,
selectedItems: selectedItems,
isMultiSelect: true,
onItemsSelected: (List<SelectableItem> items) {
setState(() {
selectedItems = items;
});
debugPrint('Selected ${items.length} items');
},
maxSelections: 5, // Optional: limit to 5 selections
labelText: 'Choose multiple items',
hintText: 'Search and select items...',
)
Multi-Select with No Limit #
UniversalSelector(
items: items,
selectedItems: selectedItems,
isMultiSelect: true,
onItemsSelected: (List<SelectableItem> items) {
setState(() {
selectedItems = items;
});
},
// No maxSelections = unlimited selections
)
Hide Subtitles #
UniversalSelector(
items: items,
selectedItem: selectedItem,
onItemSelected: (SelectableItem item) {
setState(() {
selectedItem = item;
});
},
showSubtitle: false, // Hide subtitles
)
Fuzzy Search #
The widget includes intelligent fuzzy search that helps users find items even with typos:
- Exact matches - Perfect matches for item name, subtitle, or search data
- Starts with - Query is the beginning of item name, subtitle, or search data
- Contains - Query is contained within item name, subtitle, or search data
- Fuzzy search - Finds items even with typos using Levenshtein distance
Examples:
"appl"
→ finds"Apple"
"bannana"
→ finds"Banana"
"united sttes"
→ finds"United States"
Use Cases #
The Universal Selector is perfect for:
- Country Selection - Choose countries with flags and codes
- Language Selection - Pick languages with flags
- Category Selection - Select product categories
- Color Selection - Choose colors with visual indicators
- Settings Selection - Pick app settings or preferences
- Multi-Select Scenarios - Choose multiple items like:
- Multiple countries for shipping
- Multiple languages for app localization
- Multiple categories for filtering
- Multiple colors for theme customization
- Multiple tags or labels
- Any List Selection - Works with any data you need to select from
Running the Example #
To see the widget in action:
cd example
flutter run
The example demonstrates:
- Multiple use cases (fruits, countries, colors)
- Fuzzy search with typos support
- Beautiful dark and light themes
- Responsive design for all screen sizes
- Optimized performance for weak devices
Author #
Stanislav Bozhko
Email: stas.bozhko@gmail.com
GitHub: @stanislavworldin
Support #
If you find this package helpful, consider buying me a coffee! ☕