ControlledMultiSelect<T> class

Reactive multi-selection dropdown with automatic state management.

A high-level multi-select widget that provides automatic state management through the controlled component pattern. Supports both controller-based and callback-based state management with comprehensive customization options for item presentation, selection behavior, and popup management.

Features

  • Multiple selection: Select and deselect multiple items simultaneously
  • Flexible item rendering: Custom builders for complete visual control over items
  • Selection indicators: Built-in checkboxes or custom selection indicators
  • Popup positioning: Configurable alignment and constraints for the dropdown
  • Keyboard navigation: Full keyboard support with Space for selection toggle
  • Form integration: Automatic validation and form field registration

Usage Patterns

Controller-based (recommended for complex state):

final controller = MultiSelectController<String>(['apple']);

ControlledMultiSelect<String>(
  controller: controller,
  items: ['apple', 'banana', 'cherry', 'date'],
  itemBuilder: (context, item, selected) => ListTile(
    leading: Checkbox(value: selected),
    title: Text(item),
  ),
  placeholder: Text('Choose fruits'),
)

Callback-based (simple state management):

List<String> selectedFruits = [];

ControlledMultiSelect<String>(
  initialValue: selectedFruits,
  onChanged: (fruits) => setState(() => selectedFruits = fruits?.toList() ?? []),
  items: ['apple', 'banana', 'cherry'],
  itemBuilder: (context, item, selected) => Text(item),
)
Inheritance
Mixed-in types
Available extensions

Constructors

ControlledMultiSelect({Key? key, MultiSelectController<T>? controller, ValueChanged<Iterable<T>?>? onChanged, bool enabled = true, Iterable<T>? initialValue, Widget? placeholder, bool filled = false, FocusNode? focusNode, BoxConstraints? constraints, BoxConstraints? popupConstraints, OverlayConfiguration? overlayConfiguration, BorderRadiusGeometry? borderRadius, EdgeInsetsGeometry? padding, WidgetStatePropertyDelegate<Decoration>? decoration, bool disableHoverEffect = false, bool canUnselect = true, bool autoClosePopover = false, Predicate<Iterable<T>>? showValuePredicate, Widget? expandIcon = const SelectExpandIcon(), required SelectPopupBuilder popup, required SelectValueBuilder<T> itemBuilder, SelectValueSelectionHandler<Iterable<T>>? valueSelectionHandler, SelectValueSelectionPredicate<Iterable<T>>? valueSelectionPredicate, bool? adaptiveOverlay})
Creates a ControlledMultiSelect.
const

Properties

adaptiveOverlay → bool?
Whether the popup may adapt to a different presentation on mobile platforms (see showOverlay's adaptive parameter).
final
asBuilder → NeverWidgetBuilder

Available on Widget, provided by the WidgetExtension extension

Converts this widget to a builder function.
no setter
autoClosePopover → bool
Whether popup auto-closes after selection.
final
base → TextModifier

Available on Widget, provided by the TextExtension extension

Applies base (default) font size.
no setter
black → TextModifier

Available on Widget, provided by the TextExtension extension

Applies black font weight (900).
no setter
blockQuote → TextModifier

Available on Widget, provided by the TextExtension extension

Applies block quote style with left border.
no setter
bold → TextModifier

Available on Widget, provided by the TextExtension extension

Applies bold font weight (700).
no setter
borderRadius → BorderRadiusGeometry?
Border radius of the select trigger.
final
canUnselect → bool
Whether clicking selected item deselects it.
final
constraints → BoxConstraints?
Size constraints for the select trigger.
final
controller → MultiSelectController<T>?
The controller for managing this component's value programmatically.
final
decoration → WidgetStatePropertyDelegate<Decoration>?
Overrides the decoration of the select trigger, resolved per WidgetState. See SelectTheme.decoration.
final
disableHoverEffect → bool
Whether to disable hover effects.
final
ellipsis → TextModifier

Available on Widget, provided by the TextExtension extension

Applies ellipsis overflow to text.
no setter
enabled → bool
Whether this component is enabled and accepts user input.
final
expandIcon → Widget?
Expand icon for the select
final
extraBold → TextModifier

Available on Widget, provided by the TextExtension extension

Applies extra-bold font weight (800).
no setter
extraLight → TextModifier

Available on Widget, provided by the TextExtension extension

Applies extra-light font weight (200).
no setter
filled → bool
Whether to use filled appearance style.
final
firstP → TextModifier

Available on Widget, provided by the TextExtension extension

Applies paragraph style for the first paragraph (no top spacing).
no setter
focusNode → FocusNode?
Focus node for keyboard navigation.
final
foreground → TextModifier

Available on Widget, provided by the TextExtension extension

Applies standard foreground color.
no setter
h1 → TextModifier

Available on Widget, provided by the TextExtension extension

Applies heading 1 style.
no setter
h2 → TextModifier

Available on Widget, provided by the TextExtension extension

Applies heading 2 style with bottom border.
no setter
h3 → TextModifier

Available on Widget, provided by the TextExtension extension

Applies heading 3 style.
no setter
h4 → TextModifier

Available on Widget, provided by the TextExtension extension

Applies heading 4 style.
no setter
hashCode → int
The hash code for this object.
no setterinherited
iconDestructiveForeground → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with destructive foreground color.
no setter
iconLarge → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with large size theme.
no setter
iconMedium → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with medium size theme.
no setter
iconMutedForeground → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with muted foreground color.
no setter
iconPrimary → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with primary color.
no setter
iconPrimaryForeground → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with primary foreground color.
no setter
iconSecondary → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with secondary color.
no setter
iconSecondaryForeground → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with secondary foreground color.
no setter
iconSmall → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with small size theme.
no setter
iconX2Large → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with extra-extra large size theme.
no setter
iconX2Small → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with extra-extra small size theme.
no setter
iconX3Large → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with extra-extra-extra large size theme.
no setter
iconX3Small → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with extra-extra-extra small size theme.
no setter
iconX4Large → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with extra-extra-extra-extra large size theme.
no setter
iconX4Small → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with extra-extra-extra-extra small size theme.
no setter
iconXLarge → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with extra large size theme.
no setter
iconXSmall → WrappedIcon

Available on Widget, provided by the IconExtension extension

Wraps the icon with extra small size theme.
no setter
initialValue → Iterable<T>?
The initial value for this component when no controller is provided.
final
inlineCode → TextModifier

Available on Widget, provided by the TextExtension extension

Applies inline code style with background and padding.
no setter
italic → TextModifier

Available on Widget, provided by the TextExtension extension

Applies italic font style.
no setter
itemBuilder → SelectValueBuilder<Iterable<T>>
Builder for rendering selected values.
no setteroverride
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
large → TextModifier

Available on Widget, provided by the TextExtension extension

Applies large font size.
no setter
lead → TextModifier

Available on Widget, provided by the TextExtension extension

Applies lead paragraph style with muted color.
no setter
li → TextModifier

Available on Widget, provided by the TextExtension extension

Applies list item style with bullet point.
no setter
light → TextModifier

Available on Widget, provided by the TextExtension extension

Applies light font weight (300).
no setter
medium → TextModifier

Available on Widget, provided by the TextExtension extension

Applies medium font weight (500).
no setter
modify → TextModifier

Available on Widget, provided by the TextExtension extension

Applies primary foreground color modifier.
no setter
mono → TextModifier

Available on Widget, provided by the TextExtension extension

Applies monospace font family.
no setter
multiItemBuilder → SelectValueBuilder<T>
Builder for rendering individual items in multi-select mode.
final
muted → TextModifier

Available on Widget, provided by the TextExtension extension

Applies muted foreground color.
no setter
normal → TextModifier

Available on Widget, provided by the TextExtension extension

Applies normal font weight (400).
no setter
onChanged → ValueChanged<Iterable<T>?>?
Callback invoked when the component's value changes.
final
overlayConfiguration → OverlayConfiguration?
Overrides the OverlayConfiguration used to present the popup. When null, a default PopoverConfiguration is used (PopoverConstraint.anchorFixedSize, Alignment.topCenter).
final
p → TextModifier

Available on Widget, provided by the TextExtension extension

Applies paragraph style with top spacing.
no setter
padding → EdgeInsetsGeometry?
Internal padding of the select trigger.
final
placeholder → Widget?
Placeholder widget shown when nothing is selected.
final
Builder for popup content.
final
popupConstraints → BoxConstraints?
Size constraints for the popup menu.
final
primaryForeground → TextModifier

Available on Widget, provided by the TextExtension extension

Applies primary foreground color.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
sans → TextModifier

Available on Widget, provided by the TextExtension extension

Applies sans-serif font family.
no setter
secondaryForeground → TextModifier

Available on Widget, provided by the TextExtension extension

Applies secondary foreground color.
no setter
semiBold → TextModifier

Available on Widget, provided by the TextExtension extension

Applies semi-bold font weight (600).
no setter
showValuePredicate → Predicate<Iterable<T>>?
Predicate for showing value in trigger.
final
singleLine → TextModifier

Available on Widget, provided by the TextExtension extension

Constrains text to a single line without wrapping.
no setter
small → TextModifier

Available on Widget, provided by the TextExtension extension

Applies small font size.
no setter
textCenter → TextModifier

Available on Widget, provided by the TextExtension extension

Centers text horizontally.
no setter
textEnd → TextModifier

Available on Widget, provided by the TextExtension extension

Aligns text to the end (right in LTR, left in RTL).
no setter
textJustify → TextModifier

Available on Widget, provided by the TextExtension extension

Justifies text alignment.
no setter
textLarge → TextModifier

Available on Widget, provided by the TextExtension extension

Applies large text style.
no setter
textLeft → TextModifier

Available on Widget, provided by the TextExtension extension

Left-aligns text.
no setter
textMuted → TextModifier

Available on Widget, provided by the TextExtension extension

Applies muted text style with muted color.
no setter
textRight → TextModifier

Available on Widget, provided by the TextExtension extension

Right-aligns text.
no setter
textSmall → TextModifier

Available on Widget, provided by the TextExtension extension

Applies small text style.
no setter
textStart → TextModifier

Available on Widget, provided by the TextExtension extension

Aligns text to the start (left in LTR, right in RTL).
no setter
thin → TextModifier

Available on Widget, provided by the TextExtension extension

Applies thin font weight (100).
no setter
underline → TextModifier

Available on Widget, provided by the TextExtension extension

Applies underline text decoration.
no setter
valueSelectionHandler → SelectValueSelectionHandler<Iterable<T>>?
Custom selection handler logic.
final
valueSelectionPredicate → SelectValueSelectionPredicate<Iterable<T>>?
Predicate for testing selection state.
final
x2Large → TextModifier

Available on Widget, provided by the TextExtension extension

Applies 2x large font size.
no setter
x3Large → TextModifier

Available on Widget, provided by the TextExtension extension

Applies 3x large font size.
no setter
x4Large → TextModifier

Available on Widget, provided by the TextExtension extension

Applies 4x large font size.
no setter
x5Large → TextModifier

Available on Widget, provided by the TextExtension extension

Applies 5x large font size.
no setter
x6Large → TextModifier

Available on Widget, provided by the TextExtension extension

Applies 6x large font size.
no setter
x7Large → TextModifier

Available on Widget, provided by the TextExtension extension

Applies 7x large font size.
no setter
x8Large → TextModifier

Available on Widget, provided by the TextExtension extension

Applies 8x large font size.
no setter
x9Large → TextModifier

Available on Widget, provided by the TextExtension extension

Applies 9x large font size.
no setter
xLarge → TextModifier

Available on Widget, provided by the TextExtension extension

Applies extra-large font size.
no setter
xSmall → TextModifier

Available on Widget, provided by the TextExtension extension

Applies extra-small font size.
no setter

Methods

build(BuildContext context) → Widget
Describes the part of the user interface represented by this widget.
override
center({Key? key}) → Widget

Available on Widget, provided by the WidgetExtension extension

Centers this widget horizontally and vertically.
clip({Clip clipBehavior = Clip.hardEdge}) → Widget

Available on Widget, provided by the WidgetExtension extension

Clips this widget to a rectangle.
clipOval({Clip clipBehavior = Clip.antiAlias}) → Widget

Available on Widget, provided by the WidgetExtension extension

Clips this widget to an oval shape.
clipPath({Clip clipBehavior = Clip.antiAlias, required CustomClipper<Path> clipper}) → Widget

Available on Widget, provided by the WidgetExtension extension

Clips this widget to a custom path.
clipRRect({BorderRadiusGeometry borderRadius = BorderRadius.zero, Clip clipBehavior = Clip.antiAlias}) → Widget

Available on Widget, provided by the WidgetExtension extension

Clips this widget to a rounded rectangle.
constrained({double? minWidth, double? maxWidth, double? minHeight, double? maxHeight, double? width, double? height}) → Widget

Available on Widget, provided by the WidgetExtension extension

Wraps this widget in a ConstrainedBox with specified constraints.
createElement() → StatelessElement
Creates a StatelessElement to manage this widget's location in the tree.
inherited
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
expanded({int flex = 1}) → Widget

Available on Widget, provided by the WidgetExtension extension

Makes this widget expanded within a Flex parent (Row/Column).
intrinsic({double? stepWidth, double? stepHeight}) → Widget

Available on Widget, provided by the WidgetExtension extension

Sizes this widget to both intrinsic width and height.
intrinsicHeight() → Widget

Available on Widget, provided by the WidgetExtension extension

Sizes this widget to its intrinsic height.
intrinsicWidth({double? stepWidth, double? stepHeight}) → Widget

Available on Widget, provided by the WidgetExtension extension

Sizes this widget to its intrinsic width.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
positioned({Key? key, double? left, double? top, double? right, double? bottom}) → Widget

Available on Widget, provided by the WidgetExtension extension

Positions this widget absolutely within a Stack.
sized({double? width, double? height, double? size}) → Widget

Available on Widget, provided by the WidgetExtension extension

Wraps this widget in a SizedBox with specified dimensions.
then(InlineSpan span) → Widget

Available on Widget, provided by the TextExtension extension

Appends an inline span to the current text widget.
thenButton({required VoidCallback onPressed, required Widget child}) → Widget

Available on Widget, provided by the TextExtension extension

Appends a button widget to the current text widget.
thenInlineCode(String text) → Widget

Available on Widget, provided by the TextExtension extension

Appends inline code to the current text widget.
thenText(String text) → Widget

Available on Widget, provided by the TextExtension extension

Appends a text span to the current text widget.
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited
transform({Key? key, required Matrix4 transform}) → Widget

Available on Widget, provided by the WidgetExtension extension

Applies a transformation matrix to this widget.
withAlign(AlignmentGeometry alignment) → Widget

Available on Widget, provided by the WidgetExtension extension

Aligns this widget within its parent.
withOpacity(double opacity) → Widget

Available on Widget, provided by the WidgetExtension extension

Applies opacity to this widget.
withPadding({double? top, double? bottom, double? left, double? right, double? horizontal, double? vertical, double? all, EdgeInsetsGeometry? padding}) → Widget

Available on Widget, provided by the WidgetExtension extension

Wraps this widget in a Padding widget.

Operators

operator ==(Object other) → bool
The equality operator.
inherited