Items Selector #

Introduction #

This package provides a flexible and customizable solution for selecting items from a list. It supports both single and multi-selection modes, as well as the ability to define initial items (either fixed and non-selectable or selectable). The package offers versatile display options, including scrollable lists (horizontally or vertically), grid views, and wrap-based layouts for dynamic, multi-line item arrangements. Additionally, it is fully generic and supports all data types, making it adaptable to various use cases.

Features #

• Supports all primitive data types (e.g., int, String, etc.), enums, and custom classes.
• Built-in state management handled by the package.
• Provides both single-select and multi-select options.
• Fully customizable widgets for selected and unselected states.
• Displays scrollable lists horizontally or vertically.
• Supports grid view and wrap-based layouts for flexible item arrangement.
• Ability to define initial items (selectable or non-selectable).
• Animation support.

How to use #

In a terminal, located at the root of your package, run this command:

flutter pub add items_selector

Options #

SingleSelectOption #

SingleSelectOption is used within the SingleListItemSelector, SingleGridItemSelector, and SingleWrapItemSelector widgets and includes two boolean properties:

• allowUnselectedInitialItems
  When the initialItems property is set, enabling this option allows those initial items to be unselected.

• allowUnselectedMainItems
  Enabling this option prevents the main items from being selected.

Row	Initial Items	Main Items	Allow Unselect Main Items	Allow Unselect Initial Items	Image
1	Y	Y	Y	Y
2	Y	Y	Y	N
3	Y	Y	N	Y
4	Y	Y	N	N
5	N	Y	N	N

MultiSelectOption #

MultiSelectOption is used within the MultiListItemSelector, MultiGridItemSelector, and MultiWrapItemSelector widgets and includes two properties:

• allowUnselectedInitialItems
  When the initialItems property is set, enabling this option allows those initial items to be unselected.

• maxItems
  Defines the maximum number of items that can be selected.

Row	Initial Items	Main Items	Allow Unselect Initial Items	Max Items	Image
1	Y	Y	Y	Y
2	Y	Y	N	Y
3	N	Y	N	Y
4	Y	Y	Y	N
5	Y	Y	N	N
6	N	Y	N	N

📌 Widgets Overview #

ListSelector, GridSelector, and WrapSelector provide a flexible solution for selecting items from a collection, supporting both single and multi-selection modes.

📋 Widget Variants #

🖼️ Layout Differences #

🔹 Common Properties (Available in All Widgets) #

🔹 Layout-Specific Properties #

⚙️ Selection Behavior #

ListSelector #

         ListSelector<YourDataType>(
                items: yourListOfItems,
                //// If set to Axis.horizontal, Row is used; if set to Axis.vertical, Column is used.
                direction: Axis.horizontal,
                // Can be SingleSelectOptions() or MultiSelectOptions() based on your requirement
                options: MultiSelectOptions(),
                // Default is SingleSelectOptions
                flexConfiguration: FlexConfiguration(
                  // You can also pass other Row or Column properties like mainAxisAlignment, crossAxisAlignment, etc.
                  spacing: 10.0,
                ),
                selectedItems: (List<YourDataType> selectedItems, _) {
                  debugPrint(selectedItems.toString());
                },
                builder: (_, index) {
                  return ItemSelector(
                    selectedItem: yourDesiredWidget(),
                    unSelectedItem: yourDesiredWidget(),
                  );
                },
              )

          ListSelector<YourDataType>.builder(
            items: yourListOfItems,
            direction: Axis.horizontal, // Set to Axis.horizontal or Axis.vertical based on layout preference
            options: SingleSelectOptions(), // Can be SingleSelectOptions() or MultiSelectOptions() based on your requirement
            listConfiguration: ListConfiguration(
              shrinkWrap: true,
              // You can also pass other ListView properties like physics, controller, etc.
            ),
            selectedItems: (List<YourDataType> selectedItems, _) {
              debugPrint(selectedItems.toString());
            },
            builder: (_, index) {
              return ItemSelector(
                selectedItem: yourDesiredWidget(),
                unSelectedItem: yourDesiredWidget(),
              );
            },
          )

        // Use ListSelector.separated if you need separators between items
          ListSelector<YourDataType>.separated(
            items: yourListOfItems,
            direction: Axis.horizontal, // Set to Axis.horizontal or Axis.vertical based on layout preference
            options: MultiSelectOptions(), // Can be SingleSelectOptions() or MultiSelectOptions() based on your requirement
            listConfiguration: ListConfiguration(
              shrinkWrap: true,
              // You can also pass other ListView properties like physics, controller, etc.
            ),
            selectedItems: (List<YourDataType> selectedItems, _) {
              debugPrint(selectedItems.toString());
            },
            separatorBuilder: (_, index) {
              return yourDesiredWidget();
            },
            builder: (_, index) {
              return ItemSelector(
                selectedItem: yourDesiredWidget(),
                unSelectedItem: yourDesiredWidget(),
              );
            },
          )

              ListSelector<YourDataType>.wheel(
                  items: yourListOfItems,
                  wheelConfiguration: WheelConfiguration(
                    // You can also pass other ListWheelScrollView properties like squeeze, controller, etc.
                    itemExtent: 60,
                    diameterRatio: 3.0,
                    perspective: 0.01,
                  ),
                  // Can be SingleSelectOptions() or MultiSelectOptions() based on your requirement
                  options: MultiSelectOptions(),
                  selectedItems: (List<YourDataType> selectedItems, _) {
                    debugPrint(selectedItems.toString());
                  },
                  builder: (_, index) {
                    return ItemSelector(
                      selectedItem: yourDesiredWidget(),
                      unSelectedItem: yourDesiredWidget(),
                    );
                  },
                )

GridSelector #

           GridSelector<yourDataType>.builder(
              items: yourListOfItems,
              // Can be SingleSelectOptions() or MultiSelectOptions() based on your requirement
              // options: SingleSelectOptions(),  // Default is SingleSelectOptions
              builderConfiguration: BuilderConfiguration(
                // You can also pass other GridView.builder properties like physics, controller, etc.
                gridDelegate: SliverGridDelegateWithMaxCrossAxisExtent(
                  maxCrossAxisExtent: 120.0,
                  crossAxisSpacing: 10.0,
                  mainAxisSpacing: 10.0,
                ),
                shrinkWrap: true,
              ),
              selectedItems: (List<yourDataType> selectedItems, _) {
                debugPrint(selectedItems.toString());
              },
              builder: (_, index) {
                return ItemSelector(
                  selectedItem: yourDesireWidget(),
                  unSelectedItem: yourDesireWidget(),
                );
              },
            ),

           GridSelector<yourDataType>.count(
              items: yourListOfItems,
              // Can be SingleSelectOptions() or MultiSelectOptions() based on your requirement
              // options: MultiSelectOptions(),  // Default is SingleSelectOptions
              countConfiguration: CountConfiguration(
                // You can also pass other GridView.count properties like physics, controller, etc.
                crossAxisCount: 3,
                shrinkWrap: true,
              ),
              selectedItems: (List<yourDataType> selectedItems, _) {
                debugPrint(selectedItems.toString());
              },
              builder: (_, index) {
                return ItemSelector(
                  selectedItem: yourDesireWidget(),
                  unSelectedItem: yourDesireWidget(),
                );
              },
            )

          GridSelector<yourDataType>.extent(
              items: yourListOfItems,
              // Can be SingleSelectOptions() or MultiSelectOptions() based on your requirement
              // options: MultiSelectOptions(),  // Default is SingleSelectOptions
              extentConfiguration: ExtentConfiguration(
                // You can also pass other GridView.extent properties like physics, controller, etc.
                maxCrossAxisExtent: 150,
                mainAxisSpacing: 10,
                crossAxisSpacing: 10,
                shrinkWrap: true,
              ),

              selectedItems: (List<yourDataType> selectedItems, _) {
                debugPrint(selectedItems.toString());
              },
              builder: (_, index) {
                return ItemSelector(
                  selectedItem: yourDesireWidget(),
                  unSelectedItem: yourDesireWidget(),
                );
              },
            )

WrapSelector #

       WrapSelector<yourDataType>(
          items: yourListOfItems,
          // Can be SingleSelectOptions() or MultiSelectOptions() based on your requirement
          // options: MultiSelectOptions(),  // Default is SingleSelectOptions
          wrapConfiguration: WrapConfiguration(
            // You can also pass other wrap properties like runAlignment, crossAxisAlignment, etc.
            spacing: 10,
            runSpacing: 20.0,
          ),
          selectedItems: (List<yourDataType> selectedItems, _) {
            debugPrint(selectedItems.toString());
          },
          builder: (_, index) {
            return ItemSelector(
              selectedItem: yourDesireWidget(),
              unSelectedItem: yourDesireWidget(),
            );
          },
        )

Examples #

⚠️ Troubleshooting #

Issue: initialItems Not Working for Custom Classes #

If you use a custom class as the item type and set the initialItems property, you might notice that the initial items are not selected when the app runs. This happens because Dart uses reference equality by default, meaning it does not automatically recognize two objects as equal even if their properties have the same values.

✅ Solution 1: Override == Operator and hashCode #

To ensure Dart correctly identifies equal objects, override the equality (==) operator and hashCode in your custom class:

class CustomItem {
  final int id;
  final String name;

  CustomItem(this.id, this.name);

  @override
  bool operator ==(Object other) =>
          identical(this, other) || (other is CustomItem && other.id == id && other.name == name);

  @override
  int get hashCode => id.hashCode ^ name.hashCode;
}

✅ Solution 2: Use the equatable Package #

Instead of manually overriding == and hashCode, you can use the equatable package to simplify equality checks.

1️⃣ Add equatable to your dependencies:

flutter pub add equatable

2️⃣ Modify your custom class to extend equatable:

import 'package:equatable/equatable.dart';

class CustomItem extends Equatable {
  final int id;
  final String name;

  const CustomItem(this.id, this.name);

  @override
  List<Object> get props => [id, name];
}

With Equatable, Dart will automatically handle equality comparisons, ensuring initialItems work correctly! 🎯