LayrzMultiSelectInput

LayrzMultiSelectInput

Multiple-value selection field with searchable dropdown list and checkboxes.

Specification Status: Derived from layrz_theme.ThemedMultiSelectInput. This documentation reflects the current layrz_theme API and is NOT YET CONFIRMED as the design for layrz_ui. Team review and design sign-off are required before implementation.

Metadata

Property	Value
Mirror	ThemedMultiSelectInput<T>
Phase	M3 Inputs
Domain	Inputs
SDK Primitive	Composes LayrzTextInput (read-only) + RawDialog for dropdown surface with checkboxes

Conformance

LayrzMultiSelectInput conforms to the Input Contract. Like all picker-style inputs, it composes LayrzTextInput internally in read-only mode and opens a selection surface on tap. The entire contract applies: labels, prefix/suffix, help affordance, focus management, padding, and validation error display.

Value Type and Selection Surface

• Value type: List<T> — a list of comparable values, one per selected item
• Selection surface: Searchable dropdown dialog with checkbox-enabled list for multiple selection
• Summary display: The field displays a summary of selected items (e.g., "3 items selected"); unselected state shows placeholder or empty
• Item support type: LayrzSelectItem<T> (same as LayrzSelectInput, see LayrzSelectInput)

Deltas from the Input Contract

Multi-Selection Behavior

// Design sketch — illustrative only
class LayrzMultiSelectInput<T> extends StatefulWidget {
  /// List of items available for selection.
  final List<LayrzSelectItem<T>> items;

  /// Callback invoked when user changes selection.
  /// Receives the list of selected items.
  final void Function(List<LayrzSelectItem<T>>)? onChanged;

  /// Currently selected values (matched against LayrzSelectItem.value).
  final List<T>? value;

  /// Whether to enable search filtering in the dropdown.
  final bool enableSearch;

  /// Whether to automatically close the dropdown after each selection.
  /// When false, user must manually close the dialog.
  final bool autoclose;

  /// Whether to defer calling onChanged until the dialog is closed.
  /// When true, selections are accumulated but onChanged fires only on close.
  final bool waitUntilClosedToSubmit;

  /// Custom filter function for search.
  /// If null, performs case-insensitive label search.
  final bool Function(String searchText, LayrzSelectItem<T>)? filter;

  /// Constraints for the dropdown dialog size.
  final BoxConstraints dialogConstraints;

  /// Height of each list item (affects scrollable area).
  final double itemExtent;

  const LayrzMultiSelectInput({
    required this.items,
    this.onChanged,
    this.value,
    this.enableSearch = true,
    this.autoclose = false,
    this.waitUntilClosedToSubmit = false,
    this.filter,
    this.dialogConstraints = const BoxConstraints(maxWidth: 500, maxHeight: 500),
    this.itemExtent = 50,
    // ... shared contract parameters (label, placeholder, prefix, suffix, etc.)
  });
}

Inherits from Input Contract

All of the following are inherited from LayrzTextInput:

• labelText and label (mutually exclusive)
• placeholder
• prefixIcon, prefixWidget, onPrefixTap (mutually exclusive icon and widget)
• suffixIcon, suffixWidget, onSuffixTap (mutually exclusive icon and widget)
• helpTitleText, helpContentText (two-part help tooltip)
• readOnly (always true for multi-select input)
• onTap (opens the dropdown)
• focusNode, controller (focus and value management)
• padding (defaults to spacing tokens)
• disabled and error display

Reference: Current layrz_theme API

ThemedMultiSelectInput<T> (source: lib/src/inputs/src/general/multiselect_input.dart):

Parameter	Type	Notes
labelText	String?	Label text (or use label Widget instead)
label	Widget?	Label widget (mutually exclusive with labelText)
items	List<ThemedSelectItem<T>>	List of selectable items
value	List<T>?	Currently selected values
onChanged	void Function(List<ThemedSelectItem<T>>)?	Callback when selection changes
prefixIcon	IconData?	Icon in prefix slot
prefixText	String?	Text in prefix slot
onPrefixTap	VoidCallback?	Prefix tap handler
enableSearch	bool	Enable search in dropdown (default: true)
autoclose	bool	Close after each selection (default: false)
waitUntilClosedToSubmit	bool	Defer onChanged until dialog closes (default: false)
disabled	bool	Disable the field (default: false)
errors	List<String>	Error messages (default: [])
hideDetails	bool	Hide error/helper text (default: false)
hideTitle	bool	Hide title in dropdown dialog (default: false)
isRequired	bool	Mark field as required (default: false)
padding	EdgeInsets?	Field padding
filter	bool Function(String, ThemedSelectItem<T>)?	Custom search filter
dialogConstraints	BoxConstraints	Dropdown dialog size
itemExtent	double	Height of each list item (default: 50)
customChild	Widget?	Replace entire input with custom widget
autoselectFirst	bool	Auto-select first item on first render (default: false)
translations	Map<String, String>	i18n strings (cancel, save, search, empty, select-all, unselect-all)
overridesLayrzTranslations	bool	Use custom translations over defaults (default: false)

Dependencies and Blockers

• LayrzTextInput — must ship first; LayrzMultiSelectInput composes it.
• LayrzTooltip — required for help affordances if using helpTitleText / helpContentText.
• Material-free TextSelectionControls — if LayrzTextInput requires copy/paste in read-only mode, this blocker applies.

Open Questions

1. Summary display format: How is the list of selected items summarized in the field? Is it "3 items selected", the list of labels, a truncated list with overflow indicator, or customizable?

2. Select all / Unselect all: Should there be buttons or checkboxes to select/unselect all items at once? Are these shown in the dropdown header or footer?

3. Value update semantics: When value changes externally, does the field automatically find and display the matching items, or is the caller responsible for keeping values in sync?

4. Dialog positioning: Should the dropdown be smart-positioned (above/below based on available space), or always below the field?

5. Checkbox visibility: Are checkboxes always shown, or only when items are clickable/selectable?

6. Search filtering: If filter is not supplied, does it search all attributes (label + searchableAttributes), or label only?

7. Keyboard navigation: Are arrow keys, Enter, and Space (for toggling checkboxes) supported for desktop?

8. Empty state text: Is there a default empty-list message, or must the caller provide one?

9. Order preservation: When items are selected, are they returned in selection order, item order, or should order be preserved separately?

---

Last updated: 2026-08-13
Related documents: Input Contract, LayrzSelectInput, Component Catalog, Design Tokens