Flutter TypeAhead

https://pub.dev/packages/flutter_typeahead
Admin
Flutter TypeAhead is a highly customizable typeahead (autocomplete) text input widget for Flutter...
Tokens:4,709
Snippets:46
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install via command line

Source: https://pub.dev/packages/flutter_typeahead/install

Use this command in your terminal to add the package to your Flutter project.

```bash
$ flutter pub add flutter_typeahead
```

--------------------------------

### Initialize flutter_typeahead Application

Source: https://pub.dev/packages/flutter_typeahead/example

Sets up the main application entry point using MaterialCupertinoFrame to provide both Material and Cupertino typeahead examples.

```dart
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:flutter_typeahead/flutter_typeahead.dart';
import 'package:flutter_typeahead_example/checkout.dart';
import 'package:flutter_typeahead_example/frame.dart';
import 'package:flutter_typeahead_example/settings.dart';
import 'package:flutter_typeahead_example/product.dart';
import 'package:flutter_typeahead_example/options.dart';

void main() => runApp(const App());

class App extends StatefulWidget {
  const App({super.key});

  @override
  State<App> createState() => _AppState();
}

class _AppState extends State<App> {
  @override
  Widget build(BuildContext context) {
    return MaterialCupertinoFrame(
      exampleBuilder: (context, controller, products, suggestions, settings) =>
          ExampleTypeAhead(
        controller: controller,
        products: products,
        settings: settings,
        suggestions: suggestions,
      ),
      settingsBuilder: (context, controller, settings) => SettingsTypeAhead(
        controller: controller,
        settings: settings,
      ),
      cupertinoExampleBuilder:
          (context, controller, products, suggestions, settings) =>
              CupertinoExampleTypeAhead(
        controller: controller,
        products: products,
        settings: settings,
        suggestions: suggestions,
      ),
      cupertinoSettingsBuilder: (context, controller, settings) =>
          CupertinoSettingsTypeAhead(
        controller: controller,
        settings: settings,
      ),
    );
  }
}

class ExampleTypeAhead extends StatelessWidget
    with SharedExampleTypeAheadConfig {
  ExampleTypeAhead({
    super.key,
    required this.controller,
    required this.products,
    required this.settings,
    required this.suggestions,
  });

  @override
  final TextEditingController controller;
  @override
  final ProductController products;
  @override
  final FieldSettings settings;

  final SuggestionsController<Product> suggestions;
```

--------------------------------

### Implement TypeAheadField in a Flutter Widget

Source: https://pub.dev/packages/flutter_typeahead/example

A comprehensive example showing the configuration of TypeAheadField with custom builders for the text field, decoration, and items.

```dart
@override
  Widget build(BuildContext context) {
    return ValueListenableBuilder(
      valueListenable: products,
      builder: (context, value, child) {
        return Padding(
          padding: const EdgeInsets.all(32),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: maybeReversed([
              TypeAheadField<Product>(
                direction: settings.direction.value,
                controller: controller,
                suggestionsController: suggestions,
                builder: (context, controller, focusNode) => TextField(
                  controller: controller,
                  focusNode: focusNode,
                  autofocus: true,
                  style: DefaultTextStyle.of(context)
                      .style
                      .copyWith(fontStyle: FontStyle.italic),
                  decoration: InputDecoration(
                    border: const OutlineInputBorder(),
                    hintText: hintText,
                  ),
                ),
                decorationBuilder: (context, child) => Material(
                  type: MaterialType.card,
                  elevation: 4,
                  borderRadius: borderRadius,
                  child: child,
                ),
                itemBuilder: (context, product) => ListTile(
                  title: Text(product.name),
                  subtitle: product.description != null
                      ? Text(
                          '${product.description!} - \$${product.price}',
                          maxLines: 1,
                          overflow: TextOverflow.ellipsis,
                        )
                      : Text('\$${product.price}'),
                ),
                debounceDuration: debounceDuration,
                hideOnSelect: settings.hideOnSelect.value,
                hideOnUnfocus: settings.hideOnUnfocus.value,
                retainOnLoading: settings.retainOnLoading.value,
                onSelected: onSuggestionSelected,
                suggestionsCallback: suggestionsCallback,
                itemSeparatorBuilder: itemSeparatorBuilder,
                listBuilder:
                    settings.gridLayout.value ? gridLayoutBuilder : null,
                constrainWidth: settings.constrainWidth.value,
              ),
              Expanded(
                child: Column(
                  children: [
                    const SizedBox(height: 32),
                    Padding(
                      padding: const EdgeInsets.symmetric(horizontal: 16),
                      child: Row(
                        children: [
                          Text('Shopping Cart',
                              style: Theme.of(context).textTheme.titleLarge),
                          const Spacer(),
                          Text(
                            'Total: \$${products.total}',
                            style: Theme.of(context).textTheme.titleMedium,
                          )
                        ],
                      ),
                    ),
                    const SizedBox(height: 8),
                    if (products.value.isNotEmpty)
                      Expanded(
                        child: ProductList(products: products),
                      )
                    else
                      Expanded(
                        child: Center(
                          child: Text(
                            'Your cart is empty',
                            style: Theme.of(context).textTheme.titleMedium,
                          ),
                        ),
                      )
                  ],
                ),
              ),
              Row(
                mainAxisAlignment: MainAxisAlignment.end,
                children: [
                  ElevatedButton(
                    onPressed: () => showDialog(
                      context: context,
                      builder: (context) => CheckoutDialog(products: products),
                    ),
                    child: const Text('Checkout'),
                  ),
                ],
              ),
            ]),
          ),
        );
      },
    );
  }
}
```

--------------------------------

### Configure TypeAhead properties and callbacks

Source: https://pub.dev/packages/flutter_typeahead/example

Defines common configuration variables and logic for suggestion selection, filtering, and UI rendering.

```dart
final String hintText = 'What are you looking for?';
  final BorderRadius borderRadius = BorderRadius.circular(10);
  void onSuggestionSelected(Product product) {
    products.value = Map.of(
      products.value
        ..update(
          product,
          (value) => value + 1,
          ifAbsent: () => 1,
        ),
    );
    controller.clear();
  }

  Future<List<Product>> suggestionsCallback(String pattern) async =>
      Future<List<Product>>.delayed(
        Duration(milliseconds: settings.loadingDelay.value ? 300 : 0),
        () => allProducts.where((product) {
          final nameLower = product.name.toLowerCase().split(' ').join('');
          final patternLower = pattern.toLowerCase().split(' ').join('');
          return nameLower.contains(patternLower);
        }).toList(),
      );

  Widget itemSeparatorBuilder(BuildContext context, int index) =>
      settings.dividers.value
          ? const Divider(height: 1)
          : const SizedBox.shrink();

  List<Widget> maybeReversed(List<Widget> children) {
    if (settings.direction.value == VerticalDirection.up) {
      return children.reversed.toList();
    }
    return children;
  }

  Widget gridLayoutBuilder(
    BuildContext context,
    List<Widget> items,
  ) {
    return GridView.builder(
      padding: const EdgeInsets.all(8),
      itemCount: items.length,
      shrinkWrap: true,
      gridDelegate: const SliverGridDelegateWithMaxCrossAxisExtent(
        maxCrossAxisExtent: 400,
        mainAxisExtent: 58,
        crossAxisSpacing: 8,
        mainAxisSpacing: 8,
      ),
      reverse: SuggestionsController.of<Product>(context).effectiveDirection ==
          VerticalDirection.up,
      itemBuilder: (context, index) => items[index],
    );
  }

  Duration get debounceDuration => settings.debounce.value
      ? const Duration(milliseconds: 300)
      : Duration.zero;
}
```

--------------------------------

### Import the package

Source: https://pub.dev/packages/flutter_typeahead/install

Include this import statement in your Dart files to access the library's functionality.

```dart
import 'package:flutter_typeahead/flutter_typeahead.dart';
```

--------------------------------

### Customizing the suggestions box

Source: https://pub.dev/packages/flutter_typeahead

Use decorationBuilder to style the suggestions container, and adjust offset or constraints to control positioning and sizing.

```dart
TypeAheadField(
  // ...
  decorationBuilder: (context, child) {
    return Material(
      type: MaterialType.card,
      elevation: 4,
      borderRadius: BorderRadius.circular(8),
      child: child,
    );
  },
  offset: Offset(0, 12),
  constraints: BoxConstraints(maxHeight: 500),
);
```

--------------------------------

### Customizing loading, error, and empty states

Source: https://pub.dev/packages/flutter_typeahead

Define custom widgets for loading, error, and empty states using the respective builder properties.

```dart
TypeAheadField(
  // ...
  loadingBuilder: (context) => const Text('Loading...'),
  errorBuilder: (context, error) => const Text('Error!'),
  emptyBuilder: (context) => const Text('No items found!'),
);
```

--------------------------------

### Scoping Suggestions Box with Overlay

Source: https://pub.dev/packages/flutter_typeahead

Wrap pages in an Overlay to prevent the suggestions box from overlapping adjacent pages in a PageView.

```dart
PageView(
  children: [
    Overlay(
      initialEntries: [
        OverlayEntry(
          builder: (context) => MyPageWithTypeAhead(),
        ),
      ],
    ),
    // ...
  ],
)
```

--------------------------------

### Static Analysis Issue 1

Source: https://pub.dev/packages/flutter_typeahead/score

Reported documentation comment issue regarding angle brackets in connector_widget.dart.

```text
  ╷
3 │ /// A simplified life-cycle widget for connecting to a resource <T>
  │                                                                 ^^^
  ╵
```

--------------------------------

### Add to pubspec.yaml

Source: https://pub.dev/packages/flutter_typeahead/install

Manually add the dependency to your pubspec.yaml file to include the package in your project.

```yaml
dependencies:
  flutter_typeahead: ^6.0.0
```

--------------------------------

### Passing Controller and FocusNode to TextField

Source: https://pub.dev/packages/flutter_typeahead

Ensure the controller and focusNode provided by the builder are passed to the TextField to enable suggestion box functionality.

```dart
TypeAheadField(
  // ...
  controller: myTextEditingController, // your custom controller, or null
  builder: (context, controller, focusNode) {
    return TextField(
      controller: controller, // note how the controller is passed
      focusNode: focusNode,
      // ...
    );
  },
);
```

--------------------------------

### Static Analysis Issue 2

Source: https://pub.dev/packages/flutter_typeahead/score

Reported documentation comment issue regarding angle brackets in connector_widget.dart.

```text
  ╷
6 │ /// On connection, a key <R> may be returned, which can later
  │                          ^^^
  ╵
```

--------------------------------

### Implement CupertinoTypeAheadField

Source: https://pub.dev/packages/flutter_typeahead/example

Configures a Cupertino-styled autocomplete field with custom builders for suggestions and decoration.

```dart
@override
  Widget build(BuildContext context) {
    return ValueListenableBuilder(
      valueListenable: products,
      builder: (context, value, child) {
        return Padding(
          padding: const EdgeInsets.all(32),
          child: Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: maybeReversed([
              CupertinoTypeAheadField<Product>(
                direction: settings.direction.value,
                controller: controller,
                suggestionsController: suggestions,
                builder: (context, controller, focusNode) => CupertinoTextField(
                  controller: controller,
                  focusNode: focusNode,
                  autofocus: true,
                  padding: const EdgeInsets.all(12),
                  placeholder: hintText,
                  placeholderStyle:
                      CupertinoTheme.of(context).textTheme.textStyle.copyWith(
                            color: CupertinoColors.placeholderText,
                            fontStyle: FontStyle.italic,
                          ),
                ),
                decorationBuilder: (context, child) => DecoratedBox(
                  decoration: BoxDecoration(
                    color: CupertinoTheme.of(context)
                        .barBackgroundColor
                        .withAlpha(255),
                    border: Border.all(
                      color: CupertinoDynamicColor.resolve(
                        CupertinoColors.systemGrey4,
                        context,
                      ),
                      width: 1,
                    ),
                    borderRadius: borderRadius,
                  ),
                  child: child,
                ),
                itemBuilder: (context, product) => CupertinoListTile(
                  title: Text(product.name),
                  subtitle: product.description != null
                      ? Text(
                          '${product.description!} - \$${product.price}',
                          maxLines: 1,
                          overflow: TextOverflow.ellipsis,
                        )
                      : Text('\$${product.price}'),
                ),
                debounceDuration: debounceDuration,
                hideOnSelect: settings.hideOnSelect.value,
                hideOnUnfocus: settings.hideOnUnfocus.value,
                retainOnLoading: settings.retainOnLoading.value,
                onSelected: onSuggestionSelected,
                suggestionsCallback: suggestionsCallback,
                itemSeparatorBuilder: itemSeparatorBuilder,
                listBuilder:
                    settings.gridLayout.value ? gridLayoutBuilder : null,
                constrainWidth: settings.constrainWidth.value,
              ),
              const SizedBox(height: 32),
              Padding(
                padding: const EdgeInsets.symmetric(horizontal: 16),
                child: Row(
                  children: [
                    Text('Shopping Cart',
                        style: CupertinoTheme.of(context)
                            .textTheme
                            .textStyle
                            .copyWith(fontSize: 24)),
                    const Spacer(),
                    Text(
                      'Total: \$${products.total}',
                      style: CupertinoTheme.of(context)
                          .textTheme
                          .textStyle
                          .copyWith(fontSize: 18),
                    )
                  ],
                ),
              ),
              const SizedBox(height: 8),
              if (products.value.isNotEmpty)
                Expanded(
                  child: CupertinoProductList(products: products),
                )
              else
                Expanded(
                  child: Center(
                    child: Text(
                      'Your cart is empty',
                      style: CupertinoTheme.of(context)
                          .textTheme
                          .textStyle
                          .copyWith(fontSize: 18),
                    ),
                  ),
                ),
              Row(
                mainAxisAlignment: MainAxisAlignment.end,
                children: [
                  CupertinoButton(
                    onPressed: () => showCupertinoDialog(
                      context: context,
                      builder: (context) =>
                          CupertinoCheckoutDialog(products: products),
                    ),
                    child: const Text('Checkout'),
                  ),
                ],
              ),
            ]),
          ),
        );
      },
    );
  }
}
```

```dart
mixin SharedExampleTypeAheadConfig {
  FieldSettings get settings;
  ProductController get products;
  TextEditingController get controller;

```

--------------------------------

### Define CupertinoExampleTypeAhead Class

Source: https://pub.dev/packages/flutter_typeahead/example

A stateless widget class definition that incorporates shared configuration for TypeAhead functionality.

```dart
class CupertinoExampleTypeAhead extends StatelessWidget
    with SharedExampleTypeAheadConfig {
  CupertinoExampleTypeAhead({
    super.key,
    required this.controller,
    required this.products,
    required this.settings,
    required this.suggestions,
  });

  @override
  final TextEditingController controller;
  @override
  final ProductController products;
  @override
  final FieldSettings settings;

  final SuggestionsController<Product> suggestions;
```

--------------------------------

### Implementing a basic TypeAheadField

Source: https://pub.dev/packages/flutter_typeahead

Use TypeAheadField to display suggestions based on user input. The builder, itemBuilder, and onSelected properties are required for basic functionality.

```dart
TypeAheadField<City>(
  suggestionsCallback: (search) => CityService.of(context).find(search),
  builder: (context, controller, focusNode) {
    return TextField(
      controller: controller,
      focusNode: focusNode,
      autofocus: true,
      decoration: InputDecoration(
        border: OutlineInputBorder(),
        labelText: 'City',
      )
    );
  },
  itemBuilder: (context, city) {
    return ListTile(
      title: Text(city.name),
      subtitle: Text(city.country),
    );
  },
  onSelected: (city) {
    Navigator.of(context).push<void>(
      MaterialPageRoute(
        builder: (context) => CityPage(city: city),
      ),
    );
  },
)
```

--------------------------------

### Customizing the TextField

Source: https://pub.dev/packages/flutter_typeahead

Use the builder property to provide a custom TextField or TextFormField. Ensure the provided controller and focusNode are attached to the widget.

```dart
TypeAheadField(
  // ...
  builder: (context, controller, focusNode) {
    return TextField(
      controller: controller,
      focusNode: focusNode,
      obscureText: true,
      decoration: InputDecoration(
        border: OutlineInputBorder(
          borderRadius: BorderRadius.circular(8),
        ),
        labelText: 'Password',
      ),
    );
  },
);
```

--------------------------------

### Refreshing Suggestions Manually

Source: https://pub.dev/packages/flutter_typeahead

Use the SuggestionsController to force a refresh of the suggestions list when caching prevents updates.

```dart
mySuggestionsController.refresh();
```

--------------------------------

### Customize TypeAheadField Animation

Source: https://pub.dev/packages/flutter_typeahead

Use transitionBuilder to define a custom animation for the suggestions box. Return the child directly to disable animations.

```dart
TypeAheadField(
  // ...
  transitionBuilder: (context, animation, child) {
    return FadeTransition(
      opacity: CurvedAnimation(
        parent: animation,
        curve: Curves.fastOutSlowIn,
      ),
      child: child,
    ),
  },
);
```

--------------------------------

### Customizing the layout with listBuilder

Source: https://pub.dev/packages/flutter_typeahead

Override the default ListView layout by providing a custom widget via the listBuilder property, such as a GridView.

```dart
TypeAheadField(
  // ...
  listBuilder: (context, children) => GridView.count(
    controller: scrollContoller,
    crossAxisCount: 2,
    crossAxisSpacing: 8,
    mainAxisSpacing: 8,
    shrinkWrap: true,
    reverse: SuggestionsController.of<City>(context).effectiveDirection ==
        VerticalDirection.up,
    children: children,
  ),
);
```
Tokens:
Raw