flutter_typeahead 1.8.0

Flutter TypeAhead #

A TypeAhead (autocomplete) widget for Flutter, where you can show suggestions to users as they type

Features #

  • Shows suggestions in an overlay that floats on top of other widgets
  • Allows you to specify what the suggestions will look like through a builder function
  • Allows you to specify what happens when the user taps a suggestion
  • Accepts all the parameters that traditional TextFields accept, like decoration, custom TextEditingController, text styling, etc.
  • Provides two versions, a normal version and a FormField version that accepts validation, submitting, etc.
  • Provides high customizability; you can customize the suggestion box decoration, the loading bar, the animation, the debounce duration, etc.

Installation #

See the installation instructions on pub.

Usage examples #

You can import the package with:

import 'package:flutter_typeahead/flutter_typeahead.dart';

For Cupertino users import:

import 'package:flutter_typeahead/cupertino_flutter_typeahead.dart';

Use it as follows:

Material Example 1: #

  textFieldConfiguration: TextFieldConfiguration(
    autofocus: true,
    style: DefaultTextStyle.of(context).style.copyWith(
      fontStyle: FontStyle.italic
    decoration: InputDecoration(
      border: OutlineInputBorder()
  suggestionsCallback: (pattern) async {
    return await BackendService.getSuggestions(pattern);
  itemBuilder: (context, suggestion) {
    return ListTile(
      leading: Icon(Icons.shopping_cart),
      title: Text(suggestion['name']),
      subtitle: Text('\$${suggestion['price']}'),
  onSuggestionSelected: (suggestion) {
      builder: (context) => ProductPage(product: suggestion)

In the code above, the textFieldConfiguration property allows us to configure the displayed TextField as we want. In this example, we are configuring the autofocus, style and decoration properties.

The suggestionsCallback is called with the search string that the user types, and is expected to return a List of data either synchronously or asynchronously. In this example, we are calling an asynchronous function called BackendService.getSuggestions which fetches the list of suggestions.

The itemBuilder is called to build a widget for each suggestion. In this example, we build a simple ListTile that shows the name and the price of the item. Please note that you shouldn't provide an onTap callback here. The TypeAhead widget takes care of that.

The onSuggestionSelected is a callback called when the user taps a suggestion. In this example, when the user taps a suggestion, we navigate to a page that shows us the information of the tapped product.

Material Example 2: #

Here's another example, where we use the TypeAheadFormField inside a Form:

final GlobalKey<FormState> _formKey = GlobalKey<FormState>();
final TextEditingController _typeAheadController = TextEditingController();
String _selectedCity;
  key: this._formKey,
  child: Padding(
    padding: EdgeInsets.all(32.0),
    child: Column(
      children: <Widget>[
          'What is your favorite city?'
          textFieldConfiguration: TextFieldConfiguration(
            controller: this._typeAheadController,
            decoration: InputDecoration(
              labelText: 'City'
          suggestionsCallback: (pattern) {
            return CitiesService.getSuggestions(pattern);
          itemBuilder: (context, suggestion) {
            return ListTile(
              title: Text(suggestion),
          transitionBuilder: (context, suggestionsBox, controller) {
            return suggestionsBox;
          onSuggestionSelected: (suggestion) {
            this._typeAheadController.text = suggestion;
          validator: (value) {
            if (value.isEmpty) {
              return 'Please select a city';
          onSaved: (value) => this._selectedCity = value,
        SizedBox(height: 10.0,),
          child: Text('Submit'),
          onPressed: () {
            if (this._formKey.currentState.validate()) {
                content: Text('Your Favorite City is ${this._selectedCity}')

Here, we assign to the controller property of the textFieldConfiguration a TextEditingController that we call _typeAheadController. We use this controller in the onSuggestionSelected callback to set the value of the TextField to the selected suggestion.

The validator callback can be used like any FormField.validator function. In our example, it checks whether a value has been entered, and displays an error message if not. The onSaved callback is used to save the value of the field to the _selectedCity member variable.

The transitionBuilder allows us to customize the animation of the suggestion box. In this example, we are returning the suggestionsBox immediately, meaning that we don't want any animation.

Cupertino Example: #

Please see the Cupertino code in the example project.

Known Issues #

Animations #

Placing TypeAheadField in widgets with animations may cause the suggestions box to resize incorrectly. Since animation times are variable, this has to be corrected manually at the end of the animation. You will need to add a SuggestionsBoxController described below and the following code for the AnimationController.

void Function(AnimationStatus) _statusListener;

void initState() {
  _statusListener = (AnimationStatus status) {
    if (status == AnimationStatus.completed ||
        status == AnimationStatus.dismissed) {


  void dispose() {

Dialogs #

There is a known issue with opening dialogs where the suggestions box will sometimes appear too small. This is a timing issue caused by the animations described above. Currently, showDialog has a duration of 150 ms for the animations. TypeAheadField has a delay of 170 ms to compensate for this. Until the end of the animation can be properly detected and fixed using the solution above, this temporary fix will work most of the time. If the suggestions box is too small, closing and reopening the keyboard will usually fix the issue.

Cupertino #

The Cupertino classes in TypeAhead are still new. There are also differences in the Cupertino widgets vs the Material ones. Some behavior will not translate when moving between the two.

Customizations #

TypeAhead widgets consist of a TextField and a suggestion box that shows as the user types. Both are highly customizable

Customizing the TextField #

You can customize the text field using the textFieldConfiguration property. You provide this property with an instance of TextFieldConfiguration, which allows you to configure all the usual properties of TextField, like decoration, style, controller, focusNode, autofocus, enabled, etc.

Customizing the suggestions box #

TypeAhead provides default configurations for the suggestions box. You can, however, override most of them. This is done by passing a SuggestionsBoxDecoration to the suggestionsBoxDecoration property.

Use the offsetX property in SuggestionsBoxDecoration to shift the suggestions box along the x-axis. You may also pass BoxConstraints to constraints in SuggestionsBoxDecoration to adjust the width and height of the suggestions box. Using the two together will allow the suggestions box to be placed almost anywhere.

Customizing the loader, the error and the "no items found" message #

You can use the loadingBuilder, errorBuilder and noItemsFoundBuilder to customize their corresponding widgets. For example, to show a custom error widget:

errorBuilder: (BuildContext context, Object error) =>
    style: TextStyle(
      color: Theme.of(context).errorColor

By default, the suggestions box will maintain the old suggestions while new suggestions are being retrieved. To show a circular progress indicator during retrieval instead, set keepSuggestionsOnLoading to false.

Hiding the suggestions box #

There are three scenarios when you can hide the suggestions box.

Set hideOnLoading to true to hide the box while suggestions are being retrieved. This will also ignore the loadingBuilder. Set hideOnEmpty to true to hide the box when there are no suggestions. This will also ignore the noItemsFoundBuilder. Set hideOnError to true to hide the box when there is an error retrieving suggestions. This will also ignore the errorBuilder.

By default, the suggestions box will automatically hide when the keyboard is hidden. To change this behavior, set hideSuggestionsOnKeyboardHide to false.

Customizing the animation #

You can customize the suggestion box animation through 3 parameters: the animationDuration, the animationStart, and the transitionBuilder.

The animationDuration specifies how long the animation should take, while the animationStart specified what point (between 0.0 and 1.0) the animation should start from. The transitionBuilder accepts the suggestionsBox and animationController as parameters, and should return a widget that uses the animationController to animate the display of the suggestionsBox. For example:

transitionBuilder: (context, suggestionsBox, animationController) =>
    child: suggestionsBox,
    opacity: CurvedAnimation(
      parent: animationController,
      curve: Curves.fastOutSlowIn

This uses FadeTransition to fade the suggestionsBox into the view. Note how the animationController was provided as the parent of the animation.

In order to fully remove the animation, transitionBuilder should simply return the suggestionsBox. This callback could also be used to wrap the suggestionsBox with any desired widgets, not necessarily for animation.

Customizing the debounce duration #

The suggestions box does not fire for each character the user types. Instead, we wait until the user is idle for a duration of time, and then call the suggestionsCallback. The duration defaults to 300 milliseconds, but can be configured using the debounceDuration parameter.

Customizing the offset of the suggestions box #

By default, the suggestions box is displayed 5 pixels below the TextField. You can change this by changing the suggestionsBoxVerticalOffset property.

Customizing the decoration of the suggestions box #

You can also customize the decoration of the suggestions box using the suggestionsBoxDecoration property. For example, to remove the elevation of the suggestions box, you can write:

suggestionsBoxDecoration: SuggestionsBoxDecoration(
  elevation: 0.0

Customizing the growth direction of the suggestions list #

By default, the list grows towards the bottom. However, you can use the direction property to customize the growth direction to be one of AxisDirection.down or AxisDirection.up, the latter of which will cause the list to grow up, where the first suggestion is at the bottom of the list, and the last suggestion is at the top.

Set autoFlipDirection to true to allow the suggestions list to automatically flip direction whenever it detects that there is not enough space for the current direction. This is useful for scenarios where the TypeAheadField is in a scrollable widget or when the developer wants to ensure the list is always viewable despite different user screen sizes.

Controlling the suggestions box #

Manual control of the suggestions box can be achieved by creating an instance of SuggestionsBoxController and passing it to the suggestionsBoxController property. This will allow you to manually open, close, toggle, or resize the suggestions box.

For more information #

Visit the API Documentation

Team: #

AbdulRahman AlHamaliS McDowallKenneth Liang

Shout out to the contributors! #

This project is the result of the collective effort of contributors who participated effectively by submitting pull requests, reporting issues, and answering questions. Thank you for your proactiveness, and we hope flutter_typeahead made your lifes at least a little easier!

How you can help #

Contribution Guidelines

1.8.0 - 23/01/2020 #

  • Change from List to Iterable for flexibility
  • Added onTap property to TextFieldConfiguration
  • Added offsetX property to SuggestionsBoxDecoration and CupertinoSuggestionsBoxDecoration
  • Support iOS 13 dark mode
  • Bug fixes

1.7.0 - 16/10/2019 #

  • Updated keyboard_visibility dependency
  • Scolling bug fix
  • Added new property enableInteractiveSelection
  • Fix disposing overlay

Thanks to MisterJimson, davidmartos96, pparadox11, diegoveloper

1.6.1 - 05/06/2019 #

  • Fixed onChanged not being called for TypeAheadFormField

1.6.0 - 19/05/2019 #

  • Added CupertinoTypeAheadField for Cupertino users
  • Updated example project
  • Bug fixes

1.5.0 - 25/04/2019 #

  • Added suggestionsBoxController property and SuggestionsBoxController class to allow manual control of the suggestions box
  • Fix suggestions box height problems in dialogs
  • Add textDirection property to TextFieldConfiguration

1.4.1 - 09/04/2019 #

  • Fixed BoxConstraints width parameters being ignored in SuggestionsBoxDecoration

1.4.0 - 26/03/2019 #

  • Added property autoFlipDirection to allow automatic direction flipping if there is not enough space for the suggestions list

1.3.0 - 19/03/2019 #

  • Limit number of suggestionsCallbacks until current call is finished

1.2.1 - 19/03/2019 #

  • Bug fixes & optimizations

1.2.0 - 05/03/2019 #

  • Added property keepSuggestionsOnLoading
  • Changed default behavior: suggestions box will no longer show circular progress indicator when loading; it will maintain previous results if available

1.1.0 - 01/03/2019 #

  • Suggestions box now closes on keyboard hide by default
  • Added property hideSuggestionsOnKeyboardHide
  • Width now properly resizes on orientation changes
  • Suggestions box will display above keyboard when keyboard hides the box for AxisDirection.Up
  • Fix FocusNode errors
  • Fix keyboard height calculation

1.0.4/5 - 21/02/2019 #

  • Fix suggestions being called on TextBox focus

1.0.3 - 12/02/2019 #

  • Resize suggestion box when scrolling

1.0.2 - 07/02/2019 #

  • Bug fix for maxHeight property

1.0.1 - 06/02/2019 #

  • Added properties hideOnLoading, hideOnEmpty, and hideOnError to hide the suggestions box

0.6.1 - 26/01/2019 #

  • Allow types
  • Add documentation for direction: option.

0.6.0 - 23/01/2019 #

  • Added property direction to allow the suggestions to grow either up or down

0.5.2 - 19/01/2019 #

  • Added contributing guidelines and reverse sorted the CHANGLELOG.md file.

0.5.1 - 10/01/2019 #

  • Bug fixes

0.5.0 - 05/01/2019 #

  • Added the hasScrollbar property which allows the optional display of a Scrollbar
  • Fixed the case where the suggestion box becomes hidden behind the keyboard
  • Fixed the bug of not disposing the animations controller

0.4.1 - 20/09/2018 #

  • Added property getImmediateSuggestions to the form field implementation

0.4.0 - 20/09/2018 #

  • Added property getImmediateSuggestions to allow fetching suggestions before the user types
  • Added assertion in the form field to disallow having initialValue and textFieldConfiguration.controller defined at the same time

0.3.0 - 15/09/2018 #

  • Added a constraints property to the SuggestionsBoxDecorations which allows to set the height and width of the suggestions box

0.2.1 - 04/09/2018 #

  • Added mention of 'autocomplete' in README and pubspec
  • Executed 'flutter format'

0.2.0 - 02/09/2018 #

  • Changed the suggestions box decoration to decorate a material sheet instead of decorating a container
  • Moved the TextField properties inside a class called TextFieldConfiguration, which is provided to the TypeAhead widgets through a textFieldConfiguration property. This was done to decrease the clutter in the interface
  • Added more configuration properties to the TextField
  • Added a configurable vertical offset for the suggestions box
  • Changed the mechanism used to open/close the suggestions box
  • Added meta-tags to README for SEO
  • Updated the GIF to show the changes
  • Added "How you can help" section to README

0.1.2 - 31/08/2018 #

  • Small fix to README

0.1.1 - 31/08/2018 #

  • Fixed CHANGELOG.
  • Small fix to documentation

0.1.0 - 31/08/2018 #

  • Initial Release.


example #

A usage example of flutter_typeahead

Getting Started #

For help getting started with Flutter, view our online documentation.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  flutter_typeahead: ^1.8.0

2. Install it

You can install packages from the command line:

with Flutter:

$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:flutter_typeahead/flutter_typeahead.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Feb 24, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.1
  • pana: 0.13.5
  • Flutter: 1.12.13+hotfix.7

Health suggestions

Format lib/cupertino_flutter_typeahead.dart.

Run flutter format to format lib/cupertino_flutter_typeahead.dart.

Format lib/flutter_typeahead.dart.

Run flutter format to format lib/flutter_typeahead.dart.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.19.0 <3.0.0
flutter 0.0.0
flutter_keyboard_visibility ^0.7.0 0.7.0
Transitive dependencies
collection 1.14.11 1.14.12
meta 1.1.8
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies