AutoSuggestBox<T> class

An auto-suggest box provides a list of suggestions for a user to select from as they type.

The AutoSuggestBox combines a text input with a dropdown list of suggestions that filter as the user types. This is ideal for search scenarios or when users need to select from a large list of options.

{@tool snippet} This example shows a basic auto-suggest box:

AutoSuggestBox<String>(
  items: [
    AutoSuggestBoxItem(value: 'apple', label: 'Apple'),
    AutoSuggestBoxItem(value: 'banana', label: 'Banana'),
    AutoSuggestBoxItem(value: 'cherry', label: 'Cherry'),
  ],
  onSelected: (item) {
    print('Selected: ${item.value}');
  },
  placeholder: 'Search fruits...',
)

{@end-tool}

{@tool snippet} This example shows an auto-suggest box with custom item rendering:

AutoSuggestBox<Contact>(
  items: contacts.map((c) => AutoSuggestBoxItem(
    value: c,
    label: c.name,
    child: Row(
      children: [
        CircleAvatar(backgroundImage: NetworkImage(c.avatar)),
        SizedBox(width: 8),
        Text(c.name),
      ],
    ),
  )).toList(),
  onSelected: (item) => selectContact(item.value),
)

{@end-tool}

Keyboard navigation

When enableKeyboardControls is true (the default), users can navigate suggestions using:

• Arrow Up/Down - Navigate through suggestions
• Enter - Select the focused suggestion
• Escape - Close the suggestions overlay

See also:

• TextBox, which is used by this widget to enter user text input
• ComboBox, for selecting from a predefined list without typing
• learn.microsoft.com/en-us/windows/apps/design/controls/auto-suggest-box