multiselect_field 2.3.0

multiselect_field: ^2.3.0 copied to clipboard

New Features #

• showSelectedTick: New flag on the Standard variant to control the trailing green check icon that marks selected items. Defaults to true to preserve the existing behavior. Set to false to hide the tick when you want a cleaner menu (style still indicates selection). The selectAllOption checkbox layout continues to take precedence and is unaffected.
• menuLeadingIcon / menuTrailingIcon: New optional builders on the Standard variant (Choice<T> choice, bool isSelected) => Widget? that let you replace the default leading/trailing icons of each menu entry with your own widgets. Returning null falls back to the default behavior so you can override only specific states (e.g. only the selected state).

Internal / Refactor #

• Extracted each menu entry into a dedicated StandardMultiSelectMenuItem<T> widget class. The parent now spreads the items inline into MenuAnchor.menuChildren, preserving keyboard navigation, focus and scroll semantics of the menu.
• New pure helpers in standard_multi_select_extension.dart:
  • ChoiceMenuExtension<T>: isGroupingTitle, isSelectedIn, isFirstSelectedIn predicates used by the menu.
  • ChoiceListSearchExtension<T>.filterByValue(text): case-insensitive substring filter.
  • GlobalKeyScrollExtension.ensureVisibleCentered(): centers the pointed widget inside its scrollable ancestor.
• _isSelected, _scrollToSelectedItem and the in-place _searchElement filter logic were removed from the widget in favour of these extensions.
• trailingIcon selection now uses a switch expression over a (showTick, selectAll, isSelected) record for clearer matching.

New Features #

• labelBuilder: Optional builder callback on the Standard variant that fully overrides how the static label is rendered. Consistent with the existing builder-based API (itemMenuButton, singleSelectWidget, etc.). Default behavior is unchanged when the parameter is omitted.
• MultiSelectLabel widget + LabelType enum: Reusable label widget that centralises common rendering presets. Use as the default building block for labelBuilder:
  • LabelType.line (default): single line, no wrap.
  • LabelType.wrap: wraps up to maxLines (default 2) with ellipsis. Width collapses to the longest rendered line so trailing widgets (e.g. dropdown arrows) sit right next to the text instead of being pushed to the parent's max width.
  • LabelType.overflow: single line truncated with ellipsis.

New Features #

• searchMinHeight: Configure the minimum height of the search/filter area in the BottomSheet variant. Defaults to 200px when useTextFilter is enabled. Pass a custom value to ensure enough space for filtered results.
• BottomSheet search support: The BottomSheet variant now supports useTextFilter for real-time text filtering within the sheet.

Bug Fixes #

• Fix StateError: Bad state: No element crash when iconLeft/iconRight callbacks are used with an empty selection list
• Fix StateError on Enter key press when text filter has no matching items
• iconLeft/iconRight now receive Choice<T>? (nullable) instead of Choice<T> to reflect that selection can be empty

Breaking Changes #

• onSelect is now optional in the Standard variant. Previously required, it is now nullable across all variants. You can use onSelect, onChanged, or both.

New Feature: closeOnSelect — Auto-close menu on selection #

Automatically close the menu after each item selection. Available in all variants: Standard, BottomSheet, and Drawer.

• closeOnSelect: bool, defaults to false. When true, the menu/sheet/drawer closes immediately after an item is selected.
• Callbacks (onSelect, onChanged) fire before closing.

New Feature: onChanged callback #

Simple callback that fires only on user interaction, never on default data changes. Available in all 4 variants.

• onChanged: (List<Choice<T>> selectedItems) {}: No isFromDefaultData flag — just the selected items.
• onSelect remains unchanged (still receives the isFromDefaultData flag).
• Both are optional. Use onChanged when you only care about user-driven selections, onSelect when you need to distinguish default data.

New Feature: FieldWidth — Field width control #

Control the Standard variant width without wrapping in SizedBox.

• FieldWidth.fitContent: Field shrinks to fit its label/chips (compact inline selector).
• FieldWidth.fixed(double): Field uses a specific width in pixels.
• Default (null): Fills available width (unchanged behavior).

New Feature: iconSpacing — Dropdown icon spacing #

Control the gap between the label/chips area and the dropdown arrow icon in the Standard variant.

• iconSpacing: double, defaults to 0 (minimal gap). Only applies when iconRight is null.
• The default dropdown icon no longer uses a fixed SizedBox(40x20) wrapper, resulting in a tighter layout by default.

Bugfix #

• Fixed _cleanData crash when using selectAllOption with grouped data (null key caused null check error).

New Display Modes: .drawer() and .bottomSheet() #

Two new factory constructors for opening the selection menu in a drawer or bottom sheet.

MultiSelectField<T>.bottomSheet()

Modal bottom sheet with drag handle, customizable height, and full style control.

• BottomSheetStyle: Configure maxHeightFraction, fixedHeight, backgroundColor, borderRadius, showDragHandle, dragHandleColor, dragHandleWidth, barrierColor, and animation parameters.
• Custom trigger: Pass any child widget as the tap target, or use the built-in default trigger with label.
• Header/footer: menuHeader and menuFooter widgets inside the sheet.
• Supports all existing selection features: single/multi selection, groups, select all, custom menuContent.

MultiSelectField<T>.drawer()

Two modes depending on whether scaffoldKey is provided:

• Scaffold mode (scaffoldKey provided): Renders selection content directly. Place inside Scaffold.endDrawer or Scaffold.drawer. Use MultiSelectKeyStore to open/close programmatically.
• Overlay mode (no scaffoldKey): Renders a trigger button that opens a standalone overlay drawer on tap. Respects SafeArea, dismissible by tapping outside. Custom trigger via child.
• DrawerStyle: Configure width, backgroundColor, borderRadius, boxShadow, barrierColor, position (left/right), and animation parameters.
• DrawerPosition: Enum to control which side the drawer slides in from (left or right).

MultiSelectKeyStore — Programmatic drawer control

Singleton key store for sharing state between trigger and content widgets.

• MultiSelectKeyStore.of<T>("keyName"): Get or create a shared DrawerStore.
• store.openDrawer() / store.closeDrawer(): Open or close the Scaffold drawer programmatically from anywhere.
• MultiSelectKeyStore.dispose("keyName"): Clean up a store when no longer needed.
• MultiSelectKeyStore.disposeAll(): Remove all stores.

Shared SelectionContent<T> widget

Extracted the selection list rendering into a reusable SelectionContent<T> widget. ChipMenuContent<T> is now a backward-compatible typedef.

New Feature: MultiSelectField.chip() #

Compact chip-style dropdown for space-constrained areas like filter bars.

• MultiSelectField<T>.chip(): New factory constructor for chip variant.
• ChipSize: Proportional sizing system (extraSmall, small, medium, large, extraLarge) or custom sizes.
• ChipStyle: Color and appearance configuration with withColor() and styled() factories.
• ChipMenuStyle: Menu dimensions and style configuration.
• Customizable menu: titleMenuStyle, itemMenuStyle, titleMenuPadding for group titles.
• Flexible content: Use data for auto-generated lists or menuContent for custom widgets.

• New feature ScrollbarConfig, Now we can modify the size, color, margins, etc. of our scrollbar in a very easy way.

• Improve documentation.
• Update menu currentMenuHeight.

• Fix margin on section title.

• Fix: Resolved the issue where the menu was not adjusting correctly when the keyboard was active and there wasn't enough space below for its display. Now, the menu opens at the top in such cases. Related to issue: (https://github.com/JhonaCodes/multiselect_field/issues/8)

• UI enhancements, including padding and layout adjustments.

• New feature itemColor, Customize the colors for selected, hovered, and unselected items.

• New feature selectAllOption, You will have a default option to select all the items on your list.
• Solve transparent color on x delete widget.

• Some format tweaks.
• Update to withValues on colors.

• Use withValues on style.

• Upgrade dev lib.
• upgrade sdk version.

• Attribute label text.

• Format.

• New functionality added, now you can clear the entire current selection using cleanCurrentSelection.

• Remove unnecessary validation on didUpdateWidget, in favour isFromDefaultData

• isFromDefaultData, Helps to know if onSelect data comes from defaultData.

Breaking changes: #

• DefaultValue is no longer a function; it should now be used as defaultData: [].
• If you update the data in defaultData, it triggers the execution of onSelect(element).
• Small change on logic for didUpdateWidget.
• Improve logic for default value.
• Improve validation for selected element and title of elements.
• More improvements.

• Pick was removed in favor of Choice
• The key value can now be null to determine the group title.

• Remove default color on list background and surface
• Implement dispose for Time render Help for your testing

• New feature isMandatory.
• Edit style Title and item from list items.

• Validate value on didUpdateWidget, helps to avoid continuous calling.

You can now: #

• Set fixed menu width.
• Set fixed menu height.
• Set max menu width.
• Set max menu height.
• Set menu styles.
• Set menu options widget.
• Set menu options margins.
• Set left icon of main search widget.
• Set right icon of main search widget.
• Some logging to keep clear the current lifecycle status.
• Improved some logic parts, and more.

• Avoid dispose when using ListView.

• Update info.

• Initial version.