Smart Auto Suggest Box #

A highly customizable auto-suggest (autocomplete) Flutter package offering three widgets:

SmartAutoSuggestBox — floating overlay dropdown (single select)
SmartAutoSuggestView — inline suggestion list embedded in the widget tree (single select)
SmartAutoSuggestMultiSelectBox — floating overlay with multi-item selection and chips

All share the same SmartAutoSuggestDataSource API and item model.

Features #

Three display modes — floating overlay (SmartAutoSuggestBox), inline list (SmartAutoSuggestView), or multi-select (SmartAutoSuggestMultiSelectBox)
Multi-select — chip-based selection area, configurable max visible chips, "Show all" BottomSheet, max selections limit
Unified data source — SmartAutoSuggestDataSource with sync initialList and async onSearch
Smart overlay positioning — auto-repositions to the opposite side if insufficient space (SmartAutoSuggestBox only)
4-direction support — top, bottom, start, end with RTL awareness
Search modes — onNoLocalResults (default) or always (every keystroke)
Configurable debounce — control search trigger timing
Keyboard navigation — ↑ ↓ Enter Escape, auto-focus first item on desktop
Form support — SmartAutoSuggestBox.form() and SmartAutoSuggestView.form() with validation
Scrollbar — visible scrollbar thumb when the suggestion list overflows
Custom builders — item, no-results, loading state, selected item display
Theming — SmartAutoSuggestTheme (ThemeExtension) with light/dark defaults
BottomSheet ready — SmartAutoSuggestView works inside showModalBottomSheet
Internationalization — built-in i18n

Getting Started #

dependencies:
  smart_auto_suggest_box: ^0.13.0

# localization (optional, but recommended)
  flutter_localizations:
    sdk: flutter

flutter pub get

Localization setup #

To enable localizations, add the following to your MaterialApp:

import 'package:smart_auto_suggest_box/smart_auto_suggest_box.dart';
import 'package:flutter_localizations/flutter_localizations.dart'; // for GlobalMaterialLocalizations

/*
... other MaterialApp properties
*/

localizationsDelegates: const [
  SmartAutoSuggestBoxLocalizations.delegate,
  // ...app's other delegates (e.g. GlobalMaterialLocalizations.delegate)
],
supportedLocales:[
  // Add your app's supported locales here,like:
  const Locale('ar'), // Arabic
  const Locale('fa'), // Persian
  const Locale('en'), // English
  // ...other locales
],

Usage #

SmartAutoSuggestBox (floating overlay) #

SmartAutoSuggestBox<String>(
  dataSource: SmartAutoSuggestDataSource(
    itemBuilder: (context, value) => SmartAutoSuggestItem(
      value: value,
      label: value[0].toUpperCase() + value.substring(1),
    ),
    initialList: (context) => ['apple', 'banana'],
  ),
  decoration: const InputDecoration(
    labelText: 'Search fruits',
    border: OutlineInputBorder(),
  ),
  onSelected: (item) => print(item?.label),
);

SmartAutoSuggestView (inline list) #

SmartAutoSuggestView<String>(
  dataSource: SmartAutoSuggestDataSource(
    itemBuilder: (context, value) => SmartAutoSuggestItem(
      value: value,
      label: value[0].toUpperCase() + value.substring(1),
    ),
    initialList: (context) => ['apple', 'banana'],
  ),
  showListWhenEmpty: true,   // show list even when text field is empty
  listMaxHeight: 300,
  decoration: const InputDecoration(
    labelText: 'Search',
    border: OutlineInputBorder(),
  ),
  onSelected: (item) => print(item?.label),
);

Async Server Search #

SmartAutoSuggestBox<String>(   // or SmartAutoSuggestView
  dataSource: SmartAutoSuggestDataSource(
    itemBuilder: (context, value) => SmartAutoSuggestItem(
      value: value,
      label: value,
    ),
    initialList: (context) => [],
    onSearch: (context, currentItems, searchText) async {
      return await api.search(searchText);
    },
    debounce: const Duration(milliseconds: 500),
  ),
  onSelected: (item) {},
);

searchMode.always #

Call onSearch on every keystroke (after debounce):

SmartAutoSuggestBox<String>(
  dataSource: SmartAutoSuggestDataSource(
    itemBuilder: (context, value) => SmartAutoSuggestItem(
      value: value,
      label: value,
    ),
    initialList: (context) => localItems,
    onSearch: (context, current, searchText) async {
      return await api.search(searchText);
    },
    searchMode: SmartAutoSuggestSearchMode.always,
    debounce: const Duration(milliseconds: 600),
  ),
  onSelected: (item) {},
);

SmartAutoSuggestBox<String>(
  dataSource: SmartAutoSuggestDataSource(
    itemBuilder: (c, v) => SmartAutoSuggestItem(value: v, label: v),
    initialList: (c) => items,
  ),
  direction: SmartAutoSuggestBoxDirection.top,   // falls back if no space
  onSelected: (item) {},
);

Direction	Description
`bottom`	Below the text field. Falls back to `top`.
`top`	Above the text field. Falls back to `bottom`.
`start`	Start side (left in LTR). Falls back to `end`.
`end`	End side (right in LTR). Falls back to `start`.

SmartAutoSuggestView in BottomSheet #

showModalBottomSheet(
  context: context,
  isScrollControlled: true,
  useSafeArea: true,
  builder: (context) => DraggableScrollableSheet(
    expand: false,
    builder: (context, scrollController) => Column(
      children: [
        // ... drag handle, title ...
        Expanded(
          child: SmartAutoSuggestView<String>(
            dataSource: SmartAutoSuggestDataSource(
              itemBuilder: (context, value) => SmartAutoSuggestItem(
                value: value,
                label: value,
              ),
              initialList: (context) => myItems,
            ),
            showListWhenEmpty: true,
            listMaxHeight: double.infinity,
            onSelected: (item) => Navigator.pop(context),
          ),
        ),
      ],
    ),
  ),
);

Custom No-Results View #

SmartAutoSuggestBox<String>(
  dataSource: SmartAutoSuggestDataSource(
    itemBuilder: (c, v) => SmartAutoSuggestItem(value: v, label: v),
    initialList: (c) => items,
  ),
  noResultsFoundBuilder: (context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        const Icon(Icons.search_off, size: 40),
        const Text('No matching results'),
        OutlinedButton.icon(
          onPressed: () { /* add new item */ },
          icon: const Icon(Icons.add),
          label: const Text('Add new'),
        ),
      ],
    );
  },
  onSelected: (item) {},
);

Custom Item Builder #

SmartAutoSuggestBox<String>(
  dataSource: SmartAutoSuggestDataSource(
    itemBuilder: (c, v) => SmartAutoSuggestItem(value: v, label: v),
    initialList: (c) => items,
  ),
  tileHeight: 72,
  itemBuilder: (context, item) {
    return ListTile(
      leading: CircleAvatar(child: Text(item.label[0])),
      title: Text(item.label),
      subtitle: Text('Value: ${item.value}'),
      trailing: Chip(label: Text('${item.label.length}')),
    );
  },
  onSelected: (item) {},
);

Form Validation #

SmartAutoSuggestView.form(
  dataSource: SmartAutoSuggestDataSource(
    itemBuilder: (c, v) => SmartAutoSuggestItem(value: v, label: v),
    initialList: (c) => items,
  ),
  validator: (value) {
    if (value == null || value.isEmpty) return 'Required';
    return null;
  },
  autovalidateMode: AutovalidateMode.onUserInteraction,
  onSelected: (item) {},
);

Highlight Matching Text #

By default, suggestion labels highlight the matching portion in bold with the theme's primary color using SmartAutoSuggestHighlightText. You can also use it directly:

SmartAutoSuggestHighlightText(
  text: 'Apple Pie',
  query: 'app',
  // optional: baseStyle, matchStyle
)

Item Builder with Focus #

Use SmartAutoSuggestItem.builder instead of the deprecated child to build custom item widgets. The builder receives the current searchText for highlighting, and the widget is automatically wrapped in Focus for keyboard navigation:

SmartAutoSuggestItem(
  key: 'apple',
  value: 'apple',
  label: 'Apple',
  builder: (context, searchText) {
    return ListTile(
      title: SmartAutoSuggestHighlightText(
        text: 'Apple',
        query: searchText,
      ),
    );
  },
)

SmartAutoSuggestController #

Use SmartAutoSuggestController<T> to access the text input and observe the selected item from outside the widget:

final controller = SmartAutoSuggestController<String>();

// Pass to widget
SmartAutoSuggestBox<String>(
  smartController: controller,
  dataSource: SmartAutoSuggestDataSource(...),
)

// Listen to selection changes
controller.selectedItem.addListener(() {
  print('Selected: ${controller.selectedItem.value?.label}');
});

// Clear programmatically
controller.clearSelection();

// Don't forget to dispose
controller.dispose();

Note: The old controller: TextEditingController? parameter is deprecated — use smartController instead.

Selected Item Display #

By default, the selected item's label is placed into the TextField as text. Use selectedItemBuilder to show a custom widget instead:

SmartAutoSuggestBox<String>(
  dataSource: SmartAutoSuggestDataSource(
    itemBuilder: fruitItemBuilder,
    initialList: (context) => fruits,
  ),
  selectedItemBuilder: (context, item) {
    return InputDecorator(
      decoration: const InputDecoration(border: OutlineInputBorder()),
      child: Chip(
        label: Text(item.label),
        onDeleted: () {}, // tap anywhere to dismiss
      ),
    );
  },
)

Tapping the custom widget clears the selection and restores the TextField. To clear programmatically, use SmartAutoSuggestBoxState.clearSelection().

SmartAutoSuggestMultiSelectBox #

Select multiple items from a floating overlay. Selected items appear as chips below the text field.

Basic Multi-Select #

SmartAutoSuggestMultiSelectBox<String>(
  dataSource: SmartAutoSuggestDataSource(
    itemBuilder: (context, value) => SmartAutoSuggestItem(
      value: value,
      label: value[0].toUpperCase() + value.substring(1),
    ),
    initialList: (context) => ['apple', 'banana', 'cherry', 'date'],
  ),
  decoration: const InputDecoration(
    labelText: 'Select fruits',
    border: OutlineInputBorder(),
  ),
  onSelectionChanged: (selected) {
    print('Selected: ${selected.map((e) => e.label).join(', ')}');
  },
);

With Max Selections #

Limit the number of selectable items. Unselected items are disabled once the limit is reached. Tap a selected item in the overlay to deselect it.

SmartAutoSuggestMultiSelectBox<String>(
  dataSource: SmartAutoSuggestDataSource(
    itemBuilder: (context, value) => SmartAutoSuggestItem(
      value: value,
      label: value,
    ),
    initialList: (context) => items,
  ),
  maxSelections: 5,
  maxVisibleChips: 2,  // show 2 chips, then "Show all" button
  onSelectionChanged: (selected) {},
);

Multi-Select Controller #

Use SmartAutoSuggestMultiSelectController<T> to observe and manipulate selections from outside the widget:

final controller = SmartAutoSuggestMultiSelectController<String>();

// Pass to widget
SmartAutoSuggestMultiSelectBox<String>(
  smartController: controller,
  dataSource: SmartAutoSuggestDataSource(...),
)

// Listen to selection changes
controller.selectedItems.addListener(() {
  print('Count: ${controller.selectedItems.value.length}');
});

// Programmatic control
controller.select(item);
controller.deselect(item);
controller.toggleSelection(item);
controller.clearAll();

// Don't forget to dispose
controller.dispose();

Multi-Select Parameters #

Parameter	Type	Default	Description
`dataSource`	`SmartAutoSuggestDataSource<T>`	required	Data source for items
`smartController`	`SmartAutoSuggestMultiSelectController<T>?`	`null`	External controller
`maxVisibleChips`	`int`	`3`	Max chips shown before "Show all" button
`maxSelections`	`int?`	`null`	Max selectable items (`null` = unlimited)
`chipBuilder`	`Widget Function(BuildContext, item, onRemove)?`	`null`	Custom chip widget
`onSelectionChanged`	`ValueChanged<Set<SmartAutoSuggestItem<T>>>?`	`null`	Selection change callback

Theming #

Use SmartAutoSuggestTheme (a ThemeExtension) to customise colours, shadows, border radii, text styles, and more.

Via ThemeData (recommended) #

MaterialApp(
  theme: ThemeData.light().copyWith(
    extensions: [SmartAutoSuggestTheme.light()],
  ),
  darkTheme: ThemeData.dark().copyWith(
    extensions: [SmartAutoSuggestTheme.dark()],
  ),
)

Per-widget override #

SmartAutoSuggestBox<String>(
  theme: SmartAutoSuggestTheme.light().copyWith(
    overlayBorderRadius: BorderRadius.circular(12),
    selectedTileColor: Colors.amber.shade100,
  ),
  // ...
)

SmartAutoSuggestDataSource API #

Configuration (constructor parameters) #

Property	Type	Default	Description
`itemBuilder`	`SmartAutoSuggestItem<T> Function(BuildContext, T)`	required	Converts raw `T` to `SmartAutoSuggestItem<T>`
`initialList`	`List<T> Function(BuildContext)?`	`null`	Sync initial items (raw values)
`onSearch`	`Future<List<T>> Function(BuildContext, List<T>, String?)?`	`null`	Async search (returns raw values)
`searchMode`	`SmartAutoSuggestSearchMode`	`onNoLocalResults`	When to trigger `onSearch`
`debounce`	`Duration`	`400ms`	Debounce before calling `onSearch`

State (observable) #

Property	Type	Description
`items`	`ValueNotifier<Set<SmartAutoSuggestItem<T>>>`	All available items (unfiltered)
`filteredItems`	`ValueNotifier<Set<SmartAutoSuggestItem<T>>>`	Filtered/sorted items shown in overlay
`isLoading`	`ValueNotifier<bool>`	Whether an async search is in progress
`errorMessage`	`ValueNotifier<String?>`	Error message from the last failed `onSearch` call

Methods #

Method	Description
`filter(searchText, [sorter])`	Apply sorter and update `filteredItems`
`search(context, searchText)`	Trigger an async search via `onSearch`
`setItems(newItems, searchText)`	Replace all items and re-filter
`addItems(newItems, searchText)`	Merge new items into existing set and re-filter
`resetSearchState()`	Reset last query so the same search can run again
`dispose()`	Release resources (ValueNotifiers, timers)

External Control #

You can observe and control the data source from outside the widget:

final dataSource = SmartAutoSuggestDataSource<String>(
  itemBuilder: (context, value) => SmartAutoSuggestItem(
    value: value,
    label: value[0].toUpperCase() + value.substring(1),
  ),
  initialList: (context) => ['apple', 'banana', 'cherry'],
  onSearch: (context, current, searchText) async {
    return await api.search(searchText);
  },
);

// Observe filtered items
dataSource.filteredItems.addListener(() {
  print('Filtered: ${dataSource.filteredItems.value.length} items');
});

// Observe loading state
dataSource.isLoading.addListener(() {
  print('Loading: ${dataSource.isLoading.value}');
});

// Add items programmatically
dataSource.addItems({
  SmartAutoSuggestItem(value: 'date', label: 'Date'),
}, 'searchText');

// Pass to widget
SmartAutoSuggestBox<String>(
  dataSource: dataSource,
  onSelected: (item) {},
);

SmartAutoSuggestView unique parameters #

Parameter	Type	Default	Description
`listMaxHeight`	`double`	`380`	Max height of the inline suggestion list
`showListWhenEmpty`	`bool`	`true`	Show list when text field is empty

Migration from 0.1.x #

All old type names are kept as deprecated typedef aliases — no code changes required. Rename at your own pace:

Old	New
`SmartAutoSuggestBoxItem`	`SmartAutoSuggestItem`
`SmartAutoSuggestBoxDataSource`	`SmartAutoSuggestDataSource`
`SmartAutoSuggestBoxSearchMode`	`SmartAutoSuggestSearchMode`
`SmartAutoSuggestBoxSorter`	`SmartAutoSuggestSorter`
`SmartAutoSuggestBoxItemBuilder`	`SmartAutoSuggestItemBuilder`

Additional Information #

Example app — complete demo with both widgets
CHANGELOG — version history
File issues on GitHub

smart_auto_suggest_box 0.13.1 smart_auto_suggest_box: ^0.13.1 copied to clipboard

Metadata