FluentAutoSuggestBox<T> class

Main AutoSuggestBox widget - refactored and optimized

A highly customizable auto-suggest/autocomplete widget with:

  • Debounced search for performance
  • LRU caching with expiration
  • Keyboard navigation (Arrow keys, Tab, Escape, Enter)
  • Form validation support
  • Loading and error states
  • Customizable builders
  • Accessibility support
  • Recent searches tracking
  • Overlay positioning control
  • BLoC/Cubit state management support

Example usage:

// Standard usage with items:
FluentAutoSuggestBox<String>(
  items: [
    FluentAutoSuggestBoxItem(value: '1', label: 'Item 1'),
    FluentAutoSuggestBoxItem(value: '2', label: 'Item 2'),
  ],
  onSelected: (item) {
    print('Selected: ${item.label}');
  },
)

// With Cubit state management:
FluentAutoSuggestBox<Product>.cubit(
  cubit: productsCubit,
  cubitItemBuilder: (context, product, isSelected, onTap) {
    return ListTile(
      title: Text(product.name),
      selected: isSelected,
      onPressed: onTap,
    );
  },
  labelBuilder: (product) => product.name,
  onCubitSelected: (product) {
    print('Selected: ${product.name}');
  },
)
Inheritance
Available extensions

Constructors

FluentAutoSuggestBox({Key? key, required List<FluentAutoSuggestBoxItem<T>> items, TextEditingController? controller, AutoSuggestController<T>? autoSuggestController, OnTextChanged<T>? onChanged, ValueChanged<FluentAutoSuggestBoxItem<T>?>? onSelected, ValueChanged<bool>? onOverlayVisibilityChanged, ItemBuilder<T>? itemBuilder, WidgetBuilder? noResultsFoundBuilder, WidgetBuilder? loadingBuilder, ItemSorter<T>? sorter, Widget? trailingIcon, bool clearButtonEnabled = true, TextStyle? style, InputDecoration? decoration, Color? cursorColor, double? cursorHeight, Radius cursorRadius = const Radius.circular(2.0), double cursorWidth = 1.5, bool? showCursor, Brightness? keyboardAppearance, EdgeInsets scrollPadding = const EdgeInsets.all(20.0), BoxHeightStyle selectionHeightStyle = ui.BoxHeightStyle.tight, BoxWidthStyle selectionWidthStyle = ui.BoxWidthStyle.tight, TextInputAction? textInputAction, FocusNode? focusNode, bool autofocus = false, bool enableKeyboardControls = true, bool enabled = true, bool readOnly = false, List<TextInputFormatter>? inputFormatters, double maxPopupHeight = kDefaultMaxPopupHeight, Future<List<FluentAutoSuggestBoxItem<T>>> onNoResultsFound(String)?, void onError(Object error, StackTrace stack)?, double tileHeight = kDefaultItemHeight, AutoSuggestBoxDirection direction = AutoSuggestBoxDirection.below, TextInputType keyboardType = TextInputType.text, int? maxLength, Offset? offset, VoidCallback? onEditingComplete, bool enableCache = true, int cacheMaxSize = 100, Duration cacheDuration = const Duration(minutes: 30), Duration debounceDelay = const Duration(milliseconds: 300), int minSearchLength = 2})
Creates a fluent-styled auto suggest box
FluentAutoSuggestBox.cubit({Key? key, required AutoSuggestCubit<T> cubit, required CubitItemBuilder<T> cubitItemBuilder, required String labelBuilder(T item), void onCubitSelected(T item)?, Map<String, dynamic>? cubitFilters, bool showCubitStats = false, Widget cubitLoadingBuilder(BuildContext context, String query)?, Widget cubitErrorBuilder(BuildContext context, Object error, String query, VoidCallback onRetry)?, Widget cubitEmptyBuilder(BuildContext context, String query)?, TextEditingController? controller, OnTextChanged<T>? onChanged, ValueChanged<bool>? onOverlayVisibilityChanged, Widget? trailingIcon, bool clearButtonEnabled = true, TextStyle? style, InputDecoration? decoration, Color? cursorColor, double? cursorHeight, Radius cursorRadius = const Radius.circular(2.0), double cursorWidth = 1.5, bool? showCursor, Brightness? keyboardAppearance, EdgeInsets scrollPadding = const EdgeInsets.all(20.0), BoxHeightStyle selectionHeightStyle = ui.BoxHeightStyle.tight, BoxWidthStyle selectionWidthStyle = ui.BoxWidthStyle.tight, TextInputAction? textInputAction, FocusNode? focusNode, bool autofocus = false, bool enableKeyboardControls = true, bool enabled = true, bool readOnly = false, List<TextInputFormatter>? inputFormatters, double maxPopupHeight = kDefaultMaxPopupHeight, double tileHeight = kDefaultItemHeight, AutoSuggestBoxDirection direction = AutoSuggestBoxDirection.below, TextInputType keyboardType = TextInputType.text, int? maxLength, Offset? offset, VoidCallback? onEditingComplete})
Creates a fluent-styled auto suggest box with Cubit state management
FluentAutoSuggestBox.form({Key? key, required List<FluentAutoSuggestBoxItem<T>> items, TextEditingController? controller, AutoSuggestController<T>? autoSuggestController, OnTextChanged<T>? onChanged, ValueChanged<FluentAutoSuggestBoxItem<T>?>? onSelected, ValueChanged<bool>? onOverlayVisibilityChanged, ItemBuilder<T>? itemBuilder, WidgetBuilder? noResultsFoundBuilder, WidgetBuilder? loadingBuilder, ItemSorter<T>? sorter, Widget? trailingIcon, bool clearButtonEnabled = true, TextStyle? style, InputDecoration? decoration, Color? cursorColor, double? cursorHeight, Radius cursorRadius = const Radius.circular(2.0), double cursorWidth = 1.5, bool? showCursor, Brightness? keyboardAppearance, EdgeInsets scrollPadding = const EdgeInsets.all(20.0), BoxHeightStyle selectionHeightStyle = ui.BoxHeightStyle.tight, BoxWidthStyle selectionWidthStyle = ui.BoxWidthStyle.tight, FormFieldValidator<String>? validator, AutovalidateMode autovalidateMode = AutovalidateMode.disabled, TextInputAction? textInputAction, FocusNode? focusNode, bool autofocus = false, bool enableKeyboardControls = true, bool enabled = true, bool readOnly = false, List<TextInputFormatter>? inputFormatters, double maxPopupHeight = kDefaultMaxPopupHeight, Future<List<FluentAutoSuggestBoxItem<T>>> onNoResultsFound(String)?, void onError(Object error, StackTrace stack)?, double tileHeight = kDefaultItemHeight, AutoSuggestBoxDirection direction = AutoSuggestBoxDirection.below, TextInputType keyboardType = TextInputType.text, int? maxLength, Offset? offset, VoidCallback? onEditingComplete, bool enableCache = true, int cacheMaxSize = 100, Duration cacheDuration = const Duration(minutes: 30), Duration debounceDelay = const Duration(milliseconds: 300), int minSearchLength = 2})
Creates a fluent-styled auto suggest form box

Properties

autofocus → bool
final
autoSuggestController → AutoSuggestController<T>?
final
autovalidateMode → AutovalidateMode
final
cacheDuration → Duration
final
cacheMaxSize → int
final
clearButtonEnabled → bool
final
controller → TextEditingController?
final
cubit → AutoSuggestCubit<T>?
The cubit for BLoC-based state management
final
cubitEmptyBuilder → Widget Function(BuildContext context, String query)?
Builder for empty state in cubit mode
final
cubitErrorBuilder → Widget Function(BuildContext context, Object error, String query, VoidCallback onRetry)?
Builder for error state in cubit mode
final
cubitFilters → Map<String, dynamic>?
Filters to pass to the cubit search
final
cubitItemBuilder → CubitItemBuilder<T>?
Builder for items when using cubit mode
final
cubitLoadingBuilder → Widget Function(BuildContext context, String query)?
Builder for loading state in cubit mode
final
cursorColor → Color?
final
cursorHeight → double?
final
cursorRadius → Radius
final
cursorWidth → double
final
debounceDelay → Duration
final
decoration → InputDecoration?
final
direction → AutoSuggestBoxDirection
final
enableCache → bool
final
enabled → bool
final
enableKeyboardControls → bool
final
focusNode → FocusNode?
final
hashCode → int
The hash code for this object.
no setterinherited
inputFormatters → List<TextInputFormatter>?
final
isCubitMode → bool
Whether the widget is using cubit mode
no setter
itemBuilder → ItemBuilder<T>?
final
items → ValueNotifier<Set<FluentAutoSuggestBoxItem<T>>>
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
keyboardAppearance → Brightness?
final
keyboardType → TextInputType
final
labelBuilder → String Function(T item)?
Function to get label text from an item in cubit mode
final
loadingBuilder → WidgetBuilder?
final
maxLength → int?
final
maxPopupHeight → double
final
minSearchLength → int
final
noResultsFoundBuilder → WidgetBuilder?
final
offset → Offset?
final
onChanged → OnTextChanged<T>?
final
onCubitSelected → void Function(T item)?
Callback when an item is selected in cubit mode
final
onEditingComplete → VoidCallback?
final
onError → void Function(Object error, StackTrace stack)?
final
onNoResultsFound → Future<List<FluentAutoSuggestBoxItem<T>>> Function(String)?
final
onOverlayVisibilityChanged → ValueChanged<bool>?
final
onSelected → ValueChanged<FluentAutoSuggestBoxItem<T>?>?
final
readOnly → bool
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
scrollPadding → EdgeInsets
final
selectionHeightStyle → BoxHeightStyle
final
selectionWidthStyle → BoxWidthStyle
final
showCubitStats → bool
Whether to show cache statistics in cubit mode
final
showCursor → bool?
final
sorter → ItemSorter<T>?
final
style → TextStyle?
final
textInputAction → TextInputAction?
final
tileHeight → double
final
trailingIcon → Widget?
final
validator → FormFieldValidator<String>?
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<FluentAutoSuggestBox<T>>
Creates the mutable state for this widget at a given location in the tree.
override
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
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
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

Operators

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

Static Methods

defaultItemSorter<T>(String text, Set<FluentAutoSuggestBoxItem<T>> items) → Set<FluentAutoSuggestBoxItem<T>>
Default item sorter