flutter_typeahead keeps the suggestion box under your control

A floating box the same width as your field

The package is a TypeAhead, or autocomplete, widget for Flutter, and its stated feature is that suggestions appear in a floating box with the same width as the TextField. The design intent is that nothing about the look is fixed. The README says you can control all aspects, including the suggestions, the loading state, errors, the empty state, the animation, the decoration, the layout, and it comes in both Material and Cupertino flavours where every parameter is identical and only the visual defaults change. The practical case for using it is not that autocomplete is hard, it is that the built-in overlays differ per platform and per Flutter version, and a product team often wants one consistent appearance across them. The package is hosted on pub.dev, and the README points to the pub installation instructions rather than repeating the command. Once the dependency is in your `pubspec.yaml`, the import is:

import 'package:flutter_typeahead/flutter_typeahead.dart';

That single import gives you the widget in both flavours, since the package exposes a Material and a Cupertino version with identical parameters.

You build the field, the widget owns the box

The API contract is the interesting part. A `TypeAheadField` takes a `builder` callback that receives a context, a controller and a focus node, and you return the text field of your choice from it. The README is emphatic about why: it is crucial that you use the provided `controller` and `focusNode`, because they are required for the suggestions box to function. If no builder is given, the widget falls back to a simple default TextField. You can also return a `TextFormField` or any other widget that connects to a TextEditingController and a FocusNode, which is what makes the package usable inside a form with validation. The three other required pieces are `suggestionsCallback`, which does the lookup, `itemBuilder`, which renders one suggestion row, and `onSelected`, which handles the choice.

Debounce, and the old results that stay on screen

Two timing behaviours decide how the field feels, and both are configurable. First, the debounce. The suggestions box does not fire for each character typed. Instead the widget waits until the user has been idle for a duration, and only then calls the `suggestionsCallback`. The default is 300 milliseconds, and the `debounceDuration` parameter changes it. The second behaviour is less obvious and worth knowing before you complain about the UX: by default the suggestions box maintains the old suggestions while the new ones are being retrieved. If you would rather see a spinner during that window, set `keepSuggestionsOnLoading` to false. The package deliberately keeps the previous list visible by default, which avoids a flicker when the user types fast.

Hiding the box in each state, and null versus an empty list

The widget can be told to hide the suggestion box rather than show something in it, and there is a separate switch for each state. `hideOnLoading` hides it while suggestions are retrieved and ignores the `loadingBuilder`. `hideOnEmpty` does the same for the case of no results, ignoring the `emptyBuilder`. `hideOnError` hides it on a retrieval error, ignoring the `errorBuilder`. `hideOnSelect` and `hideOnUnfocus` hide it when a suggestion is picked and when the field loses focus, and both of those default to true. The three builders themselves are ordinary callbacks, so a loading row can be a plain Text widget, an error row can carry the error object, and an empty row can say no items found. There is also a blunt way to hide everything, by returning `null` from the `suggestionsCallback`, and the README is careful to distinguish that from returning an empty list, which shows the empty widget.

The list layout, the direction and the ambient scroll controller

By default the suggestions are rendered in a `ListView`, and the `listBuilder` property replaces it with anything else, a `GridView` for example. The README includes that grid example, and it contains a detail worth copying: the grid reads `SuggestionsController.of<City>(context).effectiveDirection` to decide its `reverse` flag, so the grid flips with the list. The controller also exposes the current suggestions, the loading state, the error, the open and closed state, the desired and effective direction, the stream of selected suggestions and a callback to trigger a resize. One constraint comes with the ambient scroll controller: to inherit the correct ScrollController you should not set `primary` to false, because the suggestions box provides an ambient `PrimaryScrollController` of its own. Direction is configurable too, with the list growing towards the bottom by default and `VerticalDirection.up` available, and `autoFlipDirection` set to false if you would rather it did not flip.

Positioning, decoration and animation of the box

The box itself is styleable through `decorationBuilder`, which receives the context and the child, and the README shows it wrapped in a Material card with elevation and a rounded border. Position and size come from `offset` and `constraints`, with the example setting an offset of `Offset(0, 12)` and a `BoxConstraints(maxHeight: 500)`. The animation has two knobs. `animationDuration` sets how long the transition runs, and `transitionBuilder` accepts a custom one, with the example using a `FadeTransition` over a `CurvedAnimation` with `Curves.fastOutSlowIn`. To turn the animation off entirely, you return the child directly from the transition builder. None of these defaults are sacred, which is the point: every visual decision in the overlay is a parameter rather than a fork of the package.

BSD-2-Clause, and a repository that has not moved since April

The licence is BSD-2-Clause, one of the more permissive choices for a Flutter package, with the usual conditions that the copyright notice and the disclaimer travel with copies and redistribution. The maintenance picture needs reading carefully. The repository is not archived, but the last push was on 2026-04-04, which is also the date of the most recent release, version 6.0.0. Before that came 5.1.0 on 2024-01-27 and 5.0.2 on 2024-01-11, so the gap between the 5.x line and the 6.0.0 release was more than two years, and the gap between 6.0.0 and now is over six months. That does not make the package unusable, and the repository still carries an example directory, a test directory, a CHANGELOG and an analysis options file, but it does mean that a version 6 upgrade should be read against the changelog rather than assumed compatible. The upstream project is the Flutter framework, so a major release can also arrive because Flutter itself moved.

Editorial conclusion

Adopt flutter_typeahead when you want an autocomplete field whose visual style and behaviour are both yours to define, since every part of the field and the suggestion box is set through a builder callback. Do not adopt it if you need a package that also ships the data fetching, the result model and the network layer, because this one stops at the callback boundary. Verify first that your Flutter version matches what version 6.0.0 of the package targets, since that release landed on 2026-04-04 and the repository has not been pushed to since, so you should read the CHANGELOG for breaking changes before upgrading.

Frequently asked questions

Official sources

1. AbdulRahmanAlHamali/flutter_typeahead on GitHub
2. Issues
3. License: BSD-2-Clause
4. README
5. Releases