### Generate platform files and run the example Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/example/README.md First, generate the platform-specific files for the example app using the flutter create command, specifying the target platform. Then compile and run the example with flutter run. ```bash cd example # if you are not in the example directory flutter create . --platform= # where is any of [android, ios, linux, macos, web, windows] ``` ```bash flutter run ``` -------------------------------- ### Programmatic Control Example Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Example showing how to use a SuggestionsController to programmatically control the suggestions box, set suggestions, and clear errors. ```APIDOC ## Programmatic Control Example ### Description Demonstrates how to create a SuggestionsController, pass it to a TypeAheadField, and use its methods to control the suggestions box. ### Code ```dart final SuggestionsController controller = SuggestionsController(); // Pass it to the field TypeAheadField( suggestionsController: controller, suggestionsCallback: (search) => _search(search), itemBuilder: (context, p) => ListTile(title: Text(p.name)), onSelected: (p) => print(p.name), ); // Later... controller.open(gainFocus: false); // show box without focusing controller.close(retainFocus: true); // hide box, keep field focus controller.toggle(); // flip open state if (controller.hasError) { controller.error = null; // clear an error } controller.suggestions = ['a', 'b']; // set suggestions directly controller.refresh(); // force re-request ``` ``` -------------------------------- ### isOpen Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Gets whether the suggestions box is open. Read-only; use open/close/toggle to change. ```APIDOC ## `isOpen` ### Description Whether the suggestions box is open (read-only; use `open`/`close`/`toggle`). ### Getter ```dart bool get isOpen ``` ### Source `lib/src/common/base/suggestions_controller.dart:144` ``` -------------------------------- ### focusState Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Gets the current focus state: blur, box, or field. ```APIDOC ## `focusState` ### Description Current focus state: `blur`, `box` or `field` (see below). ### Getter ```dart SuggestionsFocusState get focusState ``` ### Source `lib/src/common/base/suggestions_controller.dart:148` ``` -------------------------------- ### isLoading Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Gets or sets whether the suggestions box is currently retrieving suggestions. ```APIDOC ## `isLoading` ### Description Whether the suggestions box is currently retrieving suggestions. ### Getter ```dart bool get isLoading ``` ### Setter ```dart set isLoading(bool value) ``` ### Source `lib/src/common/base/suggestions_controller.dart:121` ``` -------------------------------- ### Subscribing to Selections and Rebuilding on State Change Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Example showing how to listen to selection streams and rebuild widgets when the controller state changes. ```APIDOC ## Subscribing to Selections and Rebuilding on State Change ### Description Demonstrates how to subscribe to the selections stream and use the ChangeNotifier API to rebuild on state changes. ### Code ```dart final SuggestionsController c = SuggestionsController(); // Stream of selected suggestions (alternative to onSelected) c.selections.listen((value) => _saveSelection(value)); // Listenable-based rebuild (ChangeNotifier API) c.addListener(() { print('open=${c.isOpen} loading=${c.isLoading} ' 'error=${c.error} count=${c.suggestions?.length}'); }); // Inside a builder of the suggestions box: @override Widget build(BuildContext context) { SuggestionsController c = SuggestionsController.of(context); return ListenableBuilder( listenable: c, builder: (context, _) => Text('${c.suggestions?.length ?? 0} results'), ); } ``` ``` -------------------------------- ### Example using TypeAheadMaterialDefaults directly Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/material-defaults.md Complete example showing how to reuse the defaults programmatically: using loadingBuilder directly, wrapping a custom itemBuilder with Material behaviors, and composing a custom decorationBuilder that keeps the default card look and adds a border. Note that the elevation check compares the static method reference, which is always non-null. ```dart import 'package:flutter/material.dart'; import 'package:flutter_typeahead/flutter_typeahead.dart'; // Reuse the defaults programmatically, e.g. to restyle them: Widget myLoading = TypeAheadMaterialDefaults.loadingBuilder(context); // Explicitly wrap a custom itemBuilder with Material behaviors // (this is what TypeAheadField does internally): SuggestionsItemBuilder wrapped = TypeAheadMaterialDefaults.itemBuilder( (context, product) => ListTile(title: Text(product.name)), ); // Compose decorations: TypeAheadField( suggestionsCallback: (s) async => ['x', 'y'], itemBuilder: (context, s) => ListTile(title: Text(s)), onSelected: (s) {}, decorationBuilder: (context, child) => Material( // keep the default card look, then add a border type: MaterialType.card, elevation: TypeAheadMaterialDefaults.decorationBuilder != null ? 4 : 0, child: Container( decoration: BoxDecoration( border: Border.all(color: Colors.grey), borderRadius: BorderRadius.circular(8), ), child: child, ), ), ) ``` -------------------------------- ### Highlight next suggestion Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Starts highlighting at index 0 or moves one index down, clamped to the last suggestion. ```dart void highlightNext() { if (highlighted == null) { highlighted = 0; } else { int max = suggestions == null ? 0 : suggestions!.length - 1; highlighted = min(highlighted! + 1, max); } } ``` -------------------------------- ### suggestions Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Gets or sets the current suggestions list. The getter returns an unmodifiable copy, and the setter copies the input and skips notification if the content is equal. ```APIDOC ## `suggestions` ### Description Gets or sets the current suggestions list. The getter returns an unmodifiable-by-caller copy (`List.of`); the setter copies the input before storing and skips the notification when the content is `listEquals`-equal to the current value. `null` means "not loaded / suppressed". ### Getter ```dart List? get suggestions ``` ### Setter ```dart set suggestions(List? value) ``` ### Source `lib/src/common/base/suggestions_controller.dart:43` ``` -------------------------------- ### highlighted Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Gets or sets the index of the highlighted suggestion. `null` means nothing is highlighted. ```APIDOC ## `highlighted` ### Description Index of the highlighted suggestion, or `null` when nothing is highlighted. ### Getter ```dart int? get highlighted ``` ### Setter ```dart set highlighted(int? value) ``` ### Source `lib/src/common/base/suggestions_controller.dart:57` ``` -------------------------------- ### Basic TypeAheadField example Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/README.md Basic usage of TypeAheadField with a suggestionsCallback, a TextField builder, itemBuilder for suggestions, and onSelected to handle selection. ```dart TypeAheadField( 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( MaterialPageRoute( builder: (context) => CityPage(city: city), ), ); }, ) ``` -------------------------------- ### Catching suggestion-load errors in consumer code Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/errors.md Consumer-side example showing how to react to suggestion-load failures using errorBuilder or hideOnError, and how to programmatically inspect/reset the error via the controller. The library catches Exception subtypes; Error subtypes are not caught. ```dart TypeAheadField( suggestionsCallback: (search) async { if (search.isEmpty) throw Exception('empty query rejected'); return _api.search(search); }, errorBuilder: (context, error) => Text('Load failed: $error'), // or hideOnError: true to suppress the box onSelected: (s) {}, itemBuilder: (context, s) => ListTile(title: Text(s)), ) // Programmatically inspect/reset the error: if (controller.hasError) { Object? cause = controller.error; // the caught Exception controller.error = null; // clears hasError controller.refresh(); // retry } ``` -------------------------------- ### CupertinoTypeAheadField Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/cupertino-typeahead-field.md Documentation for the CupertinoTypeAheadField widget, including its constructor parameters and usage examples. ```APIDOC ## CupertinoTypeAheadField ### Description A Cupertino-style typeahead field that shows suggestions as the user types. It wraps a `CupertinoTextField` and provides callbacks for suggestions, item building, selection, loading, error, and empty states. ### Constructor `CupertinoTypeAheadField({required SuggestionsCallback suggestionsCallback, required ItemBuilder itemBuilder, required ValueChanged onSelected, CupertinoTextFieldBuilder builder, DecorationBuilder decorationBuilder, LoadingBuilder loadingBuilder, ErrorBuilder errorBuilder, EmptyBuilder emptyBuilder, bool hideOnEmpty, Duration debounceDuration, VerticalDirection direction})` ### Parameters - **suggestionsCallback** (`SuggestionsCallback`) - Required - Called with the current search text to fetch suggestions. - **itemBuilder** (`ItemBuilder`) - Required - Builds a widget for each suggestion. It is always wrapped by `TypeAheadCupertinoDefaults.itemBuilder` to ensure highlighted items scroll into view. - **onSelected** (`ValueChanged`) - Required - Called when the user selects a suggestion. - **builder** (`CupertinoTextFieldBuilder`) - Optional - Builds the text field. If not provided, a default `CupertinoTextField` is used. - **decorationBuilder** (`DecorationBuilder`) - Optional - Wraps the text field with a `DefaultTextStyle` from `CupertinoTheme.of(context).textTheme.textStyle` before applying your decoration or the default. - **loadingBuilder** (`LoadingBuilder`) - Optional - Builds a widget to show while suggestions are loading. - **errorBuilder** (`ErrorBuilder`) - Optional - Builds a widget to show when the suggestions callback throws an error. - **emptyBuilder** (`EmptyBuilder`) - Optional - Builds a widget to show when there are no suggestions. - **hideOnEmpty** (`bool`) - Optional - If true, hides the suggestion box when there are no suggestions. - **debounceDuration** (`Duration`) - Optional - Delay between the last keystroke and the suggestions callback. - **direction** (`VerticalDirection`) - Optional - Direction in which the suggestion box opens (up or down). ### Example: Basic Usage ```dart import 'package:flutter/cupertino.dart'; import 'package:flutter_typeahead/flutter_typeahead.dart'; CupertinoTypeAheadField( suggestionsCallback: (search) => ContactsService.search(search), builder: (context, controller, focusNode) => CupertinoTextField( controller: controller, focusNode: focusNode, placeholder: 'Search contacts', padding: const EdgeInsets.all(12), ), itemBuilder: (context, contact) => Padding( padding: const EdgeInsets.all(8), child: Text(contact.displayName), ), onSelected: (contact) => _openContact(contact), ) ``` ### Example: Error Handling and Custom States ```dart CupertinoTypeAheadField( suggestionsCallback: (search) async { if (!_isOnline) throw Exception('No network connection'); return _backend.autocomplete(search); }, itemBuilder: (context, term) => ListTile(title: Text(term)), onSelected: (term) => _runSearch(term), loadingBuilder: (context) => const Padding( padding: EdgeInsets.all(16), child: CupertinoActivityIndicator(), ), errorBuilder: (context, error) => Padding( padding: const EdgeInsets.all(12), child: Text( 'Cannot autocomplete: $error', style: const TextStyle(color: CupertinoColors.destructiveRed), ), ), emptyBuilder: (context) => const SizedBox.shrink(), // render nothing hideOnEmpty: true, // or hide the box entirely debounceDuration: const Duration(milliseconds: 150), direction: VerticalDirection.up, ) ``` ``` -------------------------------- ### SuggestionsController constructor Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Creates a new SuggestionsController instance. The controller starts closed and unfocused with direction and effectiveDirection set to VerticalDirection.down. ```dart SuggestionsController(); ``` -------------------------------- ### highlightedSuggestion Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Gets or sets the suggestion at the highlighted index. Setting a value highlights the index of that value in the suggestions list; setting null clears the highlight. ```APIDOC ## `highlightedSuggestion` ### Description The suggestion at index `highlighted`. Setting `null` clears the highlight; setting a value highlights `suggestions?.indexOf(value)` (which is `null` if the value is not in the list, i.e. setting a non-member clears the highlight). Uses `elementAtOrNull`. ### Getter ```dart T? get highlightedSuggestion ``` ### Setter ```dart set highlightedSuggestion(T? value) ``` ### Source `lib/src/common/base/suggestions_controller.dart:93` ``` -------------------------------- ### Get selections stream Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Broadcast stream of selected suggestions (public; see select). ```dart Stream get selections ``` -------------------------------- ### direction Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Gets or sets the desired direction of the suggestions box. The box tries to open in this direction and may flip depending on configuration. ```APIDOC ## `direction` ### Description Desired direction of the suggestions box. The box tries to open in this direction and may flip depending on configuration. ### Getter ```dart VerticalDirection get direction ``` ### Setter ```dart set direction(VerticalDirection value) ``` ### Source `lib/src/common/base/suggestions_controller.dart:166` ``` -------------------------------- ### Customize animation with transitionBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/README.md Customizes the animation of the suggestions box using the transitionBuilder parameter. The example uses a FadeTransition with a CurvedAnimation and the Curves.fastOutSlowIn curve. To disable animations, return the child directly. ```dart TypeAheadField( // ... transitionBuilder: (context, animation, child) { return FadeTransition( opacity: CurvedAnimation( parent: animation, curve: Curves.fastOutSlowIn, ), child: child, ), }, ); ``` -------------------------------- ### hasError / error Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Gets whether an error is present, gets or sets the error object. Errors are cleared by setting error to null. ```APIDOC ## `hasError` / `error` ### Description `hasError` is `true` whenever `error` is non-null, and errors are cleared simply by setting `error = null`. This is the mechanism used by `SuggestionsSearch`. ### Getter (hasError) ```dart bool get hasError ``` ### Getter (error) ```dart Object? get error ``` ### Setter (error) ```dart set error(Object? value) ``` ### Source `lib/src/common/base/suggestions_controller.dart:131` ``` -------------------------------- ### CupertinoTypeAheadField example with custom decorationBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/cupertino-defaults.md Example usage of CupertinoTypeAheadField with a custom decorationBuilder that overrides the default Cupertino decoration. It uses a simple suggestions callback and item builder. ```dart import 'package:flutter/cupertino.dart'; import 'package:flutter_typeahead/flutter_typeahead.dart'; // Compose the default Cupertino card decoration with a custom wrapper: CupertinoTypeAheadField( suggestionsCallback: (s) async => ['red', 'green', 'blue'], itemBuilder: (context, s) => Text(s, style: const TextStyle(fontSize: 16)), onSelected: (s) => print(s), decorationBuilder: (context, child) => DecoratedBox( decoration: BoxDecoration( color: CupertinoColors.systemBackground, borderRadius: BorderRadius.circular(6), ), child: child, ), ) ``` -------------------------------- ### Subscribing to selections and rebuilding on state change Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Demonstrates subscribing to selections via the selections stream and rebuilding on state changes using the ChangeNotifier API. Also shows how to obtain the controller inside a builder with SuggestionsController.of and use ListenableBuilder to react to changes. ```dart final SuggestionsController c = SuggestionsController(); // Stream of selected suggestions (alternative to onSelected) c.selections.listen((value) => _saveSelection(value)); // Listenable-based rebuild (ChangeNotifier API) c.addListener(() { print('open=${c.isOpen} loading=${c.isLoading} ' 'error=${c.error} count=${c.suggestions?.length}'); }); // Inside a builder of the suggestions box: @override Widget build(BuildContext context) { SuggestionsController c = SuggestionsController.of(context); return ListenableBuilder( listenable: c, builder: (context, _) => Text('${c.suggestions?.length ?? 0} results'), ); } ``` -------------------------------- ### TypeAheadMaterialDefaults.wrapperBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/material-defaults.md Static method that wraps the suggestions box contents with a transparency material and decoration. ```APIDOC ## `TypeAheadMaterialDefaults.wrapperBuilder` ### Description Wraps the suggestions box contents: returns a function that first wraps `child` in a transparency `Material` (`MaterialType.transparency`), then applies `builder ?? decorationBuilder`. Although the declared return type is `SuggestionsItemBuilder`, the returned function has the structurally identical shape of a `SuggestionsDecorationBuilder` (`Widget Function(BuildContext, Widget)`); it is assigned to the `decorationBuilder` field in the `TypeAheadField` constructor. ### Declaration ```dart static SuggestionsItemBuilder wrapperBuilder( SuggestionsDecorationBuilder? builder, ) ``` ### Parameters - **builder** (SuggestionsDecorationBuilder?) - Optional - A custom decoration builder to apply after the transparency material. ### Returns - **SuggestionsItemBuilder** - A function that wraps the child with a transparency material and the given or default decoration. ``` -------------------------------- ### TypeAheadCupertinoDefaults.wrapperBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/cupertino-defaults.md Wraps the suggestions box contents with a default text style and optional decoration builder. ```APIDOC ## `wrapperBuilder` ### Description Wraps the suggestions box contents: returns a function that first injects a `DefaultTextStyle` from `CupertinoTheme.of(context).textTheme.textStyle`, then applies `builder ?? decorationBuilder`. The declared return type is `SuggestionsItemBuilder`, but the returned function is structurally a `SuggestionsDecorationBuilder` (`Widget Function(BuildContext, Widget)`) and is assigned to the `decorationBuilder` field in the `CupertinoTypeAheadField` constructor. ### Signature ```dart static SuggestionsItemBuilder wrapperBuilder( SuggestionsDecorationBuilder? builder, ) ``` ### Parameters - **builder** (`SuggestionsDecorationBuilder?`) - Optional - A custom decoration builder to apply. ### Returns - **SuggestionsItemBuilder** - A function that wraps the suggestions box contents. ``` -------------------------------- ### SuggestionsController constructor Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Creates a controller in the closed, unfocused state with direction = VerticalDirection.down and effectiveDirection = VerticalDirection.down. ```APIDOC ## SuggestionsController constructor ### Description Creates a controller in the closed, unfocused state with `direction = VerticalDirection.down` and `effectiveDirection = VerticalDirection.down`. ### Declaration ```dart SuggestionsController(); ``` ### Usage A controller can be created yourself and passed to `TypeAheadField.suggestionsController` / `RawTypeAheadField.suggestionsController`, or created internally. Inside `itemBuilder`/`listBuilder`/`builder` contexts, the ambient controller is reached via `SuggestionsController.of(context)`. ### Source `lib/src/common/base/suggestions_controller.dart:15` ``` -------------------------------- ### SuggestionsController.of(context) — missing provider Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/errors.md Documentation for the FlutterError thrown by SuggestionsController.of when no provider is found in the context. ```APIDOC ## SuggestionsController.of(context) ### Description Throws a `FlutterError` when called from a `BuildContext` that has no ancestor `SuggestionsControllerProvider`. This occurs when the method is invoked outside a `SuggestionsField`, `SuggestionsBox`, or `TypeAheadField` subtree. ### Error Type `FlutterError` (constructed with `FlutterError.fromParts`, including `ErrorSummary`, `ErrorDescription`, `ErrorHint`, and element description). ### Trigger Conditions - Called from a `BuildContext` with no ancestor `SuggestionsControllerProvider`. - Also triggered when `maybeOf` returns `null`. ### Source `lib/src/common/base/suggestions_controller.dart:25` (message parts at lines 26–36). ### Thrown By `SuggestionsController.of(BuildContext)` ### Error Message ``` No SuggestionsController found in the context. SuggestionsControllers are only available inside SuggestionsBox widgets. Are you inside a SuggestionsBox? ``` ### Handling in Consumer Code ```dart try { SuggestionsController c = SuggestionsController.of(context); // use c } on FlutterError catch (e) { // Not inside a suggestions box — fall back debugPrint('No controller: $e'); } // Or avoid the throw entirely: SuggestionsController? c = SuggestionsController.maybeOf(context); if (c != null) { /* ... */ } ``` ``` -------------------------------- ### Get $resizes stream Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Broadcast stream of resize requests. Internal use only. Emitted by resize(). ```dart Stream get $resizes ``` -------------------------------- ### Get $refreshes stream Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Broadcast stream of refresh requests. Internal use only. Emitted by refresh(). ```dart Stream get $refreshes ``` -------------------------------- ### effectiveDirection Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Gets or sets the actual direction after auto-flipping. Typically set by the SuggestionsField widget; do not set manually. ```APIDOC ## `effectiveDirection` ### Description Actual direction after auto-flipping, typically set by the `SuggestionsField` widget; do not set manually. Useful for reversing custom lists (see `SuggestionsList`). ### Getter ```dart VerticalDirection get effectiveDirection ``` ### Setter ```dart set effectiveDirection(VerticalDirection value) ``` ### Source `lib/src/common/base/suggestions_controller.dart:185` ``` -------------------------------- ### TypeAheadMaterialDefaults.decorationBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/material-defaults.md Static method that builds the default suggestions-box decoration. ```APIDOC ## `TypeAheadMaterialDefaults.decorationBuilder` ### Description Builds the default suggestions-box decoration: a card `Material` (`MaterialType.card`, `elevation: 4`, `BorderRadius.circular(8)`) wrapping `child`. ### Declaration ```dart static Widget decorationBuilder( BuildContext context, Widget child, ) ``` ### Parameters - **context** (BuildContext) - Required - The build context. - **child** (Widget) - Required - The child widget to wrap. ### Returns - **Widget** - The decorated suggestions box. ``` -------------------------------- ### SuggestionsController.of static method Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Returns the SuggestionsController from the closest ancestor SuggestionsControllerProvider. Throws a FlutterError when no ancestor provider exists. ```dart static SuggestionsController of(BuildContext context) ``` -------------------------------- ### retainFocus Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Gets the retainFocus argument of the most recent close() call. Read by tap/typing connectors to decide whether to reopen the box. ```APIDOC ## `retainFocus` ### Description Set to the `retainFocus` argument of the most recent `close()` call. Read by the tap/typing connectors to decide whether to reopen the box. ### Getter ```dart bool get retainFocus ``` ### Source `lib/src/common/base/suggestions_controller.dart:152` ``` -------------------------------- ### Customize suggestions box with decorationBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/README.md Customize the suggestions box appearance and positioning using decorationBuilder, offset, and constraints. ```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), ); ``` -------------------------------- ### SuggestionsAnimationBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/types.md Defines a callback that builds the open/close animation of the suggestions box. ```APIDOC ## SuggestionsAnimationBuilder ### Description Builds the open/close animation of the suggestions box. Return `child` directly to disable animation. ### Signature ```dart typedef SuggestionsAnimationBuilder = Widget Function( BuildContext context, Animation animation, Widget child, ); ``` ### Parameters - **context** (`BuildContext`) - Required - The build context. - **animation** (`Animation`) - Required - Animation value from 0 (closed) to 1 (open); driven by an `AnimationController` whose duration is `animationDuration`. - **child** (`Widget`) - Required - The box content to animate. ### Accepted By - `RawTypeAheadField.transitionBuilder` - `TypeAheadField` - `CupertinoTypeAheadField` - `SuggestionsBox.transitionBuilder` - `SuggestionsBoxAnimation.transitionBuilder` ``` -------------------------------- ### SuggestionsDecorationBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/types.md Defines a callback that wraps the suggestions box content with a decoration widget. ```APIDOC ## SuggestionsDecorationBuilder ### Description Wraps the suggestions box content with a decoration (e.g. a `Material` or `DecoratedBox`). Always built, even when the box is closed. ### Signature ```dart typedef SuggestionsDecorationBuilder = Widget Function( BuildContext context, Widget child, ); ``` ### Parameters - **context** (`BuildContext`) - Required - The build context. - **child** (`Widget`) - Required - The undecorated content of the suggestions box. ### Accepted By - `RawTypeAheadField.decorationBuilder` - `TypeAheadField` - `CupertinoTypeAheadField` - `SuggestionsBox.decorationBuilder` - `TypeAheadMaterialDefaults.wrapperBuilder` - `TypeAheadCupertinoDefaults.wrapperBuilder` ``` -------------------------------- ### gainFocus Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Gets the gainFocus argument of the most recent open() call. Read by the box connector to decide whether to focus the field when opening. ```APIDOC ## `gainFocus` ### Description Set to the `gainFocus` argument of the most recent `open()` call. Read by the box connector to decide whether to focus the field when opening. ### Getter ```dart bool get gainFocus ``` ### Source `lib/src/common/base/suggestions_controller.dart:156` ``` -------------------------------- ### SuggestionsController.of Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Same as maybeOf, but throws a FlutterError when no ancestor provider exists. ```APIDOC ## SuggestionsController.of ### Description Same as `maybeOf`, but **throws** a `FlutterError` when no ancestor provider exists (see [errors.md](../errors.md)). ### Method Signature ```dart static SuggestionsController of(BuildContext context) ``` ### Parameters - **context** (BuildContext) - Required - The build context used to look up the ancestor provider. ### Returns - `SuggestionsController` - The controller from the closest ancestor provider. ### Exceptions - `FlutterError` - Thrown when no ancestor provider exists. ### Source `lib/src/common/base/suggestions_controller.dart:25` ``` -------------------------------- ### Publish package with dart pub publish Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/CONTRIBUTING.md Uploads the package to pub.dev after committing version changes. ```bash dart pub publish ``` -------------------------------- ### Programmatic control of SuggestionsController Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Shows programmatic control of a SuggestionsController. Create a controller, pass it to a TypeAheadField, then use methods like open, close, toggle, clear error, set suggestions, and refresh. Comments in the code explain the effect of each call. ```dart final SuggestionsController controller = SuggestionsController(); // Pass it to the field TypeAheadField( suggestionsController: controller, suggestionsCallback: (search) => _search(search), itemBuilder: (context, p) => ListTile(title: Text(p.name)), onSelected: (p) => print(p.name), ); // Later... controller.open(gainFocus: false); // show box without focusing controller.close(retainFocus: true); // hide box, keep field focus controller.toggle(); // flip open state if (controller.hasError) { controller.error = null; // clear an error } controller.suggestions = ['a', 'b']; // set suggestions directly controller.refresh(); // force re-request ``` -------------------------------- ### Pass controller and focusNode in TypeAheadField builder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/README.md Required setup for the TypeAheadField builder: pass the controller and focus node to the TextField. Forgetting this causes suggestions not to change when typing. ```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, // ... ); }, ); ``` -------------------------------- ### SuggestionsListBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/types.md Defines a callback that builds a custom layout for the suggestion items. ```APIDOC ## SuggestionsListBuilder ### Description Builds a custom layout for the suggestion items (e.g. a `GridView`). `children` are the widgets produced by `itemBuilder`. `SuggestionsController.of(context)` is available inside for reading `effectiveDirection`, etc. ### Signature ```dart typedef SuggestionsListBuilder = Widget Function( BuildContext context, List children, ); ``` ### Parameters - **context** (`BuildContext`) - Required - The build context. - **children** (`List`) - Required - The built suggestion widgets, in order. ### Accepted By - `RawTypeAheadField.listBuilder` - `TypeAheadField` - `CupertinoTypeAheadField` - `SuggestionsList.listBuilder` ``` -------------------------------- ### decorationBuilder static method signature Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/material-defaults.md Signature for the default suggestions-box decoration builder. It builds a card Material (MaterialType.card, elevation: 4, BorderRadius.circular(8)) wrapping the child. ```dart static Widget decorationBuilder( BuildContext context, Widget child, ) ``` -------------------------------- ### Open suggestions box Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Opens the suggestions box. With gainFocus: false the box opens without focusing the field. No-op when already open; triggers a resize afterwards. ```dart void open({bool gainFocus = true}) { if (isOpen) return; _isOpen = true; _gainFocus = gainFocus; notifyListeners(); resize(); } ``` -------------------------------- ### SuggestionsController.maybeOf Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Returns the SuggestionsController from the closest ancestor SuggestionsControllerProvider, or null if none exists. Relies on dependOnInheritedWidgetOfExactType, so callers are rebuilt when the controller notifies. ```APIDOC ## SuggestionsController.maybeOf ### Description Returns the `SuggestionsController` from the closest ancestor `SuggestionsControllerProvider`, or `null` if none exists. Relies on `dependOnInheritedWidgetOfExactType`, so callers are rebuilt when the controller notifies. ### Method Signature ```dart static SuggestionsController? maybeOf(BuildContext context) ``` ### Parameters - **context** (BuildContext) - Required - The build context used to look up the ancestor provider. ### Returns - `SuggestionsController?` - The controller from the closest ancestor provider, or `null` if none exists. ### Source `lib/src/common/base/suggestions_controller.dart:18` ``` -------------------------------- ### CupertinoTypeAheadField Constructor Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/cupertino-typeahead-field.md Documentation for the CupertinoTypeAheadField constructor, including its parameters and default behavior. ```APIDOC ## CupertinoTypeAheadField ### Description Creates a Cupertino-style typeahead field that extends `RawTypeAheadField` and defaults visual builders to Cupertino implementations. User-supplied builders override the defaults. ### Constructor ```dart CupertinoTypeAheadField({ super.key, super.animationDuration, super.autoFlipDirection, super.autoFlipMinHeight, SuggestionsFieldBuilder? builder, super.controller, super.debounceDuration, super.direction, SuggestionsErrorBuilder? errorBuilder, super.focusNode, super.hideKeyboardOnDrag, super.hideOnEmpty, super.hideOnError, super.hideOnLoading, super.showOnFocus, super.hideOnUnfocus, super.hideOnSelect, required SuggestionsItemBuilder itemBuilder, super.itemSeparatorBuilder, super.retainOnLoading, WidgetBuilder? loadingBuilder, WidgetBuilder? emptyBuilder, required super.onSelected, super.scrollController, super.suggestionsController, required super.suggestionsCallback, super.transitionBuilder, SuggestionsDecorationBuilder? decorationBuilder, super.listBuilder, super.constraints, super.constrainWidth, super.offset, }) ``` ### Parameters - **key** (Key) - Optional - Inherited from `RawTypeAheadField`. - **animationDuration** (Duration) - Optional - Inherited from `RawTypeAheadField`. - **autoFlipDirection** (bool) - Optional - Inherited from `RawTypeAheadField`. - **autoFlipMinHeight** (double) - Optional - Inherited from `RawTypeAheadField`. - **builder** (SuggestionsFieldBuilder) - Optional - Custom suggestions field builder; defaults to `TypeAheadCupertinoDefaults.builder`. - **controller** (TextEditingController) - Optional - Inherited from `RawTypeAheadField`. - **debounceDuration** (Duration) - Optional - Inherited from `RawTypeAheadField`. - **direction** (AxisDirection) - Optional - Inherited from `RawTypeAheadField`. - **errorBuilder** (SuggestionsErrorBuilder) - Optional - Custom error builder; defaults to `TypeAheadCupertinoDefaults.errorBuilder`. - **focusNode** (FocusNode) - Optional - Inherited from `RawTypeAheadField`. - **hideKeyboardOnDrag** (bool) - Optional - Inherited from `RawTypeAheadField`. - **hideOnEmpty** (bool) - Optional - Inherited from `RawTypeAheadField`. - **hideOnError** (bool) - Optional - Inherited from `RawTypeAheadField`. - **hideOnLoading** (bool) - Optional - Inherited from `RawTypeAheadField`. - **showOnFocus** (bool) - Optional - Inherited from `RawTypeAheadField`. - **hideOnUnfocus** (bool) - Optional - Inherited from `RawTypeAheadField`. - **hideOnSelect** (bool) - Optional - Inherited from `RawTypeAheadField`. - **itemBuilder** (SuggestionsItemBuilder) - Required - Custom item builder; wrapped with `TypeAheadCupertinoDefaults.itemBuilder`. - **itemSeparatorBuilder** (WidgetBuilder) - Optional - Inherited from `RawTypeAheadField`. - **retainOnLoading** (bool) - Optional - Inherited from `RawTypeAheadField`. - **loadingBuilder** (WidgetBuilder) - Optional - Custom loading builder; defaults to `TypeAheadCupertinoDefaults.loadingBuilder`. - **emptyBuilder** (WidgetBuilder) - Optional - Custom empty builder; defaults to `TypeAheadCupertinoDefaults.emptyBuilder`. - **onSelected** (ValueChanged) - Required - Inherited from `RawTypeAheadField`. - **scrollController** (ScrollController) - Optional - Inherited from `RawTypeAheadField`. - **suggestionsController** (SuggestionsController) - Optional - Inherited from `RawTypeAheadField`. - **suggestionsCallback** (SuggestionsCallback) - Required - Inherited from `RawTypeAheadField`. - **transitionBuilder** (WidgetBuilder) - Optional - Inherited from `RawTypeAheadField`. - **decorationBuilder** (SuggestionsDecorationBuilder) - Optional - Custom decoration builder; wrapped with `TypeAheadCupertinoDefaults.wrapperBuilder`. - **listBuilder** (WidgetBuilder) - Optional - Inherited from `RawTypeAheadField`. - **constraints** (BoxConstraints) - Optional - Inherited from `RawTypeAheadField`. - **constrainWidth** (bool) - Optional - Inherited from `RawTypeAheadField`. - **offset** (double) - Optional - Inherited from `RawTypeAheadField`. ### Notes - The constructor is not `const` because of the default-wrapping in the initializer list. - Widget state (`createState`) is inherited from `RawTypeAheadField`. - Import: `package:flutter_typeahead/flutter_typeahead.dart` - Source: `lib/src/cupertino/typeahead_field.dart:12` ``` -------------------------------- ### Toggle suggestions box Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Opens if closed, closes if open (uses default open()/close() arguments). ```dart void toggle() { if (isOpen) { close(); } else { open(); } } ``` -------------------------------- ### Finalize changelog with cider release Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/CONTRIBUTING.md Finalizes the changelog by changing the Unreleased section to the new version using cider. ```bash cider release ``` -------------------------------- ### Customize loading, error, and empty messages Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/README.md Customize the loading, error, and empty states using loadingBuilder, errorBuilder, and emptyBuilder. By default, old suggestions are kept while loading; set keepSuggestionsOnLoading to false to show a progress indicator instead. ```dart TypeAheadField( // ... loadingBuilder: (context) => const Text('Loading...'), errorBuilder: (context, error) => const Text('Error!'), emptyBuilder: (context) => const Text('No items found!'), ); ``` -------------------------------- ### Customize layout with listBuilder (GridView) Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/README.md Customize the suggestions layout using listBuilder to render items in a GridView. Do not set primary to false to inherit the correct ScrollController. ```dart TypeAheadField( // ... listBuilder: (context, children) => GridView.count( controller: scrollContoller, crossAxisCount: 2, crossAxisSpacing: 8, mainAxisSpacing: 8, shrinkWrap: true, reverse: SuggestionsController.of(context).effectiveDirection == VerticalDirection.up, children: children, ), ); ``` -------------------------------- ### Add changelog entry with cider log Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/CONTRIBUTING.md Adds a changelog entry using cider. Replace with one of added, changed, deprecated, removed, fixed, or security, and with a short description of the change. ```bash cider log '' ``` -------------------------------- ### Select suggestion Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Emits the suggestion on selections. Called by the Material/Cupertino item wrappers and the keyboard ActivateIntent action; the select connector invokes onSelected and closes/focuses accordingly. ```dart void select(T suggestion) => _selectionsController.add(suggestion); ``` -------------------------------- ### SuggestionsController.maybeOf static method Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Returns the SuggestionsController from the closest ancestor SuggestionsControllerProvider, or null if none exists. Relies on dependOnInheritedWidgetOfExactType, so callers are rebuilt when the controller notifies. ```dart static SuggestionsController? maybeOf(BuildContext context) ``` -------------------------------- ### Highlight previous suggestion Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Moves the highlight one index up (highlighted - 1), clearing it at index 0. No-op when nothing is highlighted. ```dart void highlightPrevious() { if (highlighted == null) return; if (highlighted! <= 0) { highlighted = null; } else { int max = suggestions == null ? 0 : suggestions!.length - 1; highlighted = min(highlighted! - 1, max); } } ``` -------------------------------- ### TypeAheadCupertinoDefaults.decorationBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/cupertino-defaults.md Builds the default suggestions-box decoration for the Cupertino typeahead field. ```APIDOC ## `decorationBuilder` ### Description Builds the default suggestions-box decoration: a `DecoratedBox` with background `CupertinoTheme.of(context).barBackgroundColor.withAlpha(255)`, a 1 px border in resolved `CupertinoColors.systemGrey4`, and `BorderRadius.all(Radius.circular(6))`. ### Signature ```dart static Widget decorationBuilder( BuildContext context, Widget child, ) ``` ### Parameters - **context** (`BuildContext`) - Required - The build context. - **child** (`Widget`) - Required - The child widget to decorate. ### Returns - **Widget** - The decorated suggestions box. ``` -------------------------------- ### Unhighlight method Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Clears the highlight. ```dart void unhighlight() => highlighted = null; ``` -------------------------------- ### Focus suggestions box Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/suggestions-controller.md Sets focus state to box. ```dart void focusBox() { if (_focusState == SuggestionsFocusState.box) return; _focusState = SuggestionsFocusState.box; notifyListeners(); } ``` -------------------------------- ### wrapperBuilder static method signature Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/material-defaults.md Signature for the wrapperBuilder that wraps suggestions box contents. It returns a function that wraps child in a transparency Material, then applies builder ?? decorationBuilder. Although the return type is SuggestionsItemBuilder, the returned function is structurally a SuggestionsDecorationBuilder and is assigned to the decorationBuilder field. ```dart static SuggestionsItemBuilder wrapperBuilder( SuggestionsDecorationBuilder? builder, ) ``` -------------------------------- ### SuggestionsCallback typedef Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/types.md Defines the signature for the suggestion loader callback. It returns a list of suggestions or null to hide the suggestions box. Throwing exceptions from this callback is caught and surfaced through SuggestionsController.error / errorBuilder. ```dart typedef SuggestionsCallback = FutureOr?> Function(String search); ``` -------------------------------- ### TypeAheadCupertinoDefaults.loadingBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/cupertino-defaults.md Builds the default loading widget for the Cupertino typeahead field. ```APIDOC ## `loadingBuilder` ### Description Builds the default loading widget: a centered `CupertinoActivityIndicator` inside a `Padding` (vertical 16) and `Row`. ### Signature ```dart static Widget loadingBuilder(BuildContext context) ``` ### Parameters - **context** (`BuildContext`) - Required - The build context. ### Returns - **Widget** - The default loading widget. ``` -------------------------------- ### TypeAheadCupertinoDefaults.itemBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/cupertino-defaults.md Wraps a user item builder to provide Cupertino-specific item behavior. ```APIDOC ## `itemBuilder` ### Description Wraps a user `SuggestionsItemBuilder` to provide Cupertino item behavior: looks up `SuggestionsController.of(context)` and rebuilds on controller changes; when the item is highlighted, draws a container with Cupertino styling and ensures visibility; wraps the user widget in a `FocusableActionDetector` and `GestureDetector` to handle selection. ### Signature ```dart static SuggestionsItemBuilder itemBuilder( SuggestionsItemBuilder builder, ) ``` ### Parameters - **builder** (`SuggestionsItemBuilder`) - Required - The user-provided item builder. ### Returns - **SuggestionsItemBuilder** - A wrapped item builder with Cupertino behavior. ``` -------------------------------- ### RawTypeAheadField constructor Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/raw-typeahead-field.md Constructor for RawTypeAheadField with all parameters. Required parameters include builder, errorBuilder, itemBuilder, loadingBuilder, emptyBuilder, onSelected, and suggestionsCallback. All parameters are also exposed as final instance fields. ```dart const RawTypeAheadField({ super.key, this.animationDuration = const Duration(milliseconds: 200), this.autoFlipDirection = false, this.autoFlipMinHeight = 144, required this.builder, this.controller, this.debounceDuration = const Duration(milliseconds: 300), this.direction = VerticalDirection.down, required this.errorBuilder, this.focusNode, this.hideKeyboardOnDrag = false, this.hideOnEmpty = false, this.hideOnError = false, this.hideOnLoading = false, this.showOnFocus = true, this.hideOnUnfocus = true, this.hideOnSelect = true, required this.itemBuilder, this.itemSeparatorBuilder, this.retainOnLoading = true, required this.loadingBuilder, required this.emptyBuilder, required this.onSelected, this.scrollController, this.suggestionsController, required this.suggestionsCallback, this.transitionBuilder, this.decorationBuilder, this.listBuilder, this.constraints, this.constrainWidth = true, this.offset, }); ``` -------------------------------- ### TypeAheadMaterialDefaults.loadingBuilder Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/api-reference/material-defaults.md Static method that builds the default loading widget for TypeAheadField. ```APIDOC ## `TypeAheadMaterialDefaults.loadingBuilder` ### Description Builds the default loading widget: a centered `CircularProgressIndicator` inside a `Padding` (vertical 16) and `Row`. Used as the default `loadingBuilder` of `TypeAheadField`. ### Declaration ```dart static Widget loadingBuilder(BuildContext context) ``` ### Parameters - **context** (BuildContext) - Required - The build context. ### Returns - **Widget** - The default loading widget. ``` -------------------------------- ### Library export file: lib/flutter_typeahead.dart Source: https://github.com/abdulrahmanalhamali/flutter_typeahead/blob/master/_autodocs/architecture.md The only public import for the package, re-exporting 7 files. Everything under lib/src/common/box/, lib/src/common/search/, lib/src/common/field/suggestions_field*.dart, lib/src/common/base/floater.dart, and lib/src/common/base/connector_widget.dart is internal and not exported. ```dart library flutter_typeahead; export 'package:flutter_typeahead/src/common/base/suggestions_controller.dart'; export 'package:flutter_typeahead/src/common/base/types.dart'; export 'package:flutter_typeahead/src/common/field/typeahead_field.dart'; export 'package:flutter_typeahead/src/material/typeahead_field.dart'; export 'package:flutter_typeahead/src/material/material_defaults.dart'; export 'package:flutter_typeahead/src/cupertino/typeahead_field.dart'; export 'package:flutter_typeahead/src/cupertino/cupertino_defaults.dart'; ```