{"id":13465510,"url":"https://github.com/AbdulRahmanAlHamali/flutter_typeahead","last_synced_at":"2025-03-25T16:32:20.404Z","repository":{"id":37742842,"uuid":"146796846","full_name":"AbdulRahmanAlHamali/flutter_typeahead","owner":"AbdulRahmanAlHamali","description":"A TypeAhead widget for Flutter, where you can show suggestions to users as they type","archived":false,"fork":false,"pushed_at":"2024-08-16T15:31:55.000Z","size":31724,"stargazers_count":819,"open_issues_count":17,"forks_count":337,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-10-01T16:08:58.397Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AbdulRahmanAlHamali.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-30T19:25:44.000Z","updated_at":"2024-09-26T10:44:52.000Z","dependencies_parsed_at":"2024-06-18T12:24:48.893Z","dependency_job_id":null,"html_url":"https://github.com/AbdulRahmanAlHamali/flutter_typeahead","commit_stats":{"total_commits":510,"total_committers":74,"mean_commits":6.891891891891892,"dds":0.6274509803921569,"last_synced_commit":"07db5879ada1d1edd0e0509877a33e9f28585b2c"},"previous_names":[],"tags_count":84,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdulRahmanAlHamali%2Fflutter_typeahead","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdulRahmanAlHamali%2Fflutter_typeahead/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdulRahmanAlHamali%2Fflutter_typeahead/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdulRahmanAlHamali%2Fflutter_typeahead/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AbdulRahmanAlHamali","download_url":"https://codeload.github.com/AbdulRahmanAlHamali/flutter_typeahead/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222088567,"owners_count":16928979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T15:00:31.410Z","updated_at":"2025-03-25T16:32:20.390Z","avatar_url":"https://github.com/AbdulRahmanAlHamali.png","language":"Dart","funding_links":[],"categories":["Components","组件","UI [🔝](#readme)","Dart"],"sub_categories":["UI"],"readme":"\u003cmeta name='keywords' content='flutter, typeahead, autocomplete, customizable, floating'\u003e\n\n[![Pub](https://img.shields.io/pub/v/flutter_typeahead)](https://pub.dev/packages/flutter_typeahead)\n\n# Flutter TypeAhead\n\nA TypeAhead (autocomplete) widget for Flutter, where you can show suggestions to\nusers as they type\n\n\u003cimg src=\"https://raw.githubusercontent.com/AbdulRahmanAlHamali/flutter_typeahead/master/flutter_typeahead.gif\" width=\"400\" height=\"auto\" alt=\"Flutter TypeAhead Demo\" /\u003e\n\n## Features\n\n- Shows suggestions in an floating box with the same width as your TextField\n- Allows controlling all aspects: suggestions, loading, errors, empty, animation, decoration, layout, etc.\n- Comes in both Material and Cupertino widget flavors\n\nFor installation, see [installation instructions](https://pub.dartlang.org/packages/flutter_typeahead/install).\n\n## Usage\n\nYou can import the package with:\n\n```dart\nimport 'package:flutter_typeahead/flutter_typeahead.dart';\n```\n\nThe package comes in both Material and Cupertino widget flavors.\nAll parameters identical, the only changes are the visual defaults.\n\n### Basic\n\n```dart\nTypeAheadField\u003cCity\u003e(\n  suggestionsCallback: (search) =\u003e CityService.of(context).find(search),\n  builder: (context, controller, focusNode) {\n    return TextField(\n      controller: controller,\n      focusNode: focusNode,\n      autofocus: true,\n      decoration: InputDecoration(\n        border: OutlineInputBorder(),\n        labelText: 'City',\n      )\n    );\n  },\n  itemBuilder: (context, city) {\n    return ListTile(\n      title: Text(city.name),\n      subtitle: Text(city.country),\n    );\n  },\n  onSelected: (city) {\n    Navigator.of(context).push\u003cvoid\u003e(\n      MaterialPageRoute(\n        builder: (context) =\u003e CityPage(city: city),\n      ),\n    );\n  },\n)\n```\n\n### Customizing the layout\n\nBy default, TypeAhead uses a `ListView` to render the items created by `itemBuilder`.  \nYou may specify a custom layout via the `listBuilder` property.\n\nFor example, to use a `GridView`:\n\n```dart\nTypeAheadField(\n  // ...\n  listBuilder: (context, children) =\u003e GridView.count(\n    controller: scrollContoller,\n    crossAxisCount: 2,\n    crossAxisSpacing: 8,\n    mainAxisSpacing: 8,\n    shrinkWrap: true,\n    reverse: SuggestionsController.of\u003cCity\u003e(context).effectiveDirection ==\n        VerticalDirection.up,\n    children: children,\n  ),\n);\n```\n\nNote: To inherit the correct `ScrollController`, please do not set `primary` to `false`.\nThe suggestions box will automatically provide an ambient `PrimaryScrollController`.\n\n### Customizing the TextField\n\nThe `TypeAheadField` will use a simple default `TextField` builder, if none is provided.\nTo customize your `TextField`, you can use the `builder` property.\n\nYou may also use a `TextFormField` or any other widget that connects to a `TextEditingController` and `FocusNode`.\n\n```dart\nTypeAheadField(\n  // ...\n  builder: (context, controller, focusNode) {\n    return TextField(\n      controller: controller,\n      focusNode: focusNode,\n      obscureText: true,\n      decoration: InputDecoration(\n        border: OutlineInputBorder(\n          borderRadius: BorderRadius.circular(8),\n        ),\n        labelText: 'Password',\n      ),\n    );\n  },\n);\n```\n\nIt is crucial that you use the provided `controller` and `focusNode` properties,\nas they are required for the suggestions box to function.\n\n### Customizing the suggestions box\n\nThe `TypeAheadField` will use a simple default decoration builder.\nTo customize the suggestions box, you can create your own decoration builder.\nYou may also specify offsets and constraints to position the suggestions box.\n\n```dart\nTypeAheadField(\n  // ...\n  decorationBuilder: (context, child) {\n    return Material(\n      type: MaterialType.card,\n      elevation: 4,\n      borderRadius: BorderRadius.circular(8),\n      child: child,\n    );\n  },\n  offset: Offset(0, 12),\n  constraints: BoxConstraints(maxHeight: 500),\n);\n```\n\n### Customizing the loading, error and empty message\n\nYou can use the `loadingBuilder`, `errorBuilder` and `emptyBuilder` to\ncustomize their corresponding widgets.\n\nFor example:\n\n```dart\nTypeAheadField(\n  // ...\n  loadingBuilder: (context) =\u003e const Text('Loading...'),\n  errorBuilder: (context, error) =\u003e const Text('Error!'),\n  emptyBuilder: (context) =\u003e const Text('No items found!'),\n);\n```\n\nBy default, the suggestions box will maintain the old suggestions while new\nsuggestions are being retrieved. To show a circular progress indicator\nduring retrieval instead, set `keepSuggestionsOnLoading` to false.\n\n### Hiding the suggestions box\n\nYou may want to hide the suggestions box when it is in certain states.\nYou can do so with the following parameters:\n\n- `hideOnLoading`: Hide the suggestions box while suggestions are being retrieved. This ignores the `loadingBuilder`.\n- `hideOnEmpty`: Hide the suggestions box when there are no suggestions. This ignores the `emptyBuilder`.\n- `hideOnError`: Hide the suggestions box when there is an error retrieving suggestions. This ignores the `errorBuilder`.\n- `hideOnSelect`: Hide the suggestions box when a suggestion is selected. `True` by default.\n- `hideOnUnfocus`: Hide the suggestions box when the `TextField` loses focus. `True` by default.\n- `hideWithKeyboard`: Hide the suggestions box when the keyboard is hidden. `True` by default.\n\nYou can also very generally hide the suggestions box by returning `null` from the `suggestionsCallback`.\nThis is different from returning an empty list, which will show the empty widget.\n\n### Customizing the animation\n\nAnimation duration can be customized using the `animationDuration` parameter.\nYou may also specify a custom animation using the `transitionBuilder` parameter.\n\nFor example:\n\n```dart\nTypeAheadField(\n  // ...\n  transitionBuilder: (context, animation, child) {\n    return FadeTransition(\n      opacity: CurvedAnimation(\n        parent: animation,\n        curve: Curves.fastOutSlowIn\n      ),\n      child: child,\n    ),\n  },\n);\n```\n\nTo disable animatons, return the `child` directly.\n\n### Customizing the debounce duration\n\nThe suggestions box does not fire for each character the user types. Instead,\nwe wait until the user is idle for a duration of time, and then call the\n`suggestionsCallback`. The duration defaults to ` 300 milliseconds``, but can be\nconfigured using the  `debounceDuration` parameter.\n\n### Customizing the direction\n\nBy default, the list grows towards the bottom. However, you can use the `direction` to specify either `VerticalDirection.down` or `VerticalDirection.up`.\n\nThe suggestions list will automatically reverse in case it is flipped.\nTo turn off this behavior, set `autoFlipDirection` to `false`.\n\n### Controlling the suggestions box\n\nYou may manually control many aspects of the suggestions box by using the `SuggestionsController` class.\n\nIt grants access to the following:\n\n- the current suggestions\n- the current loading state\n- the current error\n- the open/closed state\n- the desired and effective direction\n- the stream of selected suggestions\n- the callback to trigger a resize\n\nWhen building a widget inside of the suggestions box, you can access the controller via `SuggestionsController.of(context)`.\n\n### Controlling the focus\n\nFocus plays an important role in the suggestions box. It is used to determine when to show and hide the suggestions box.\nHowever, in certain situations you may want to control the suggestions box independently of the focus.\n\nOptions to do so are as follows:\n\nOn the `TypeAheadField`:\n\n- `showOnFocus` (default: `true`): Show the suggestions box when the `TextField` gains focus.\n- `hideOnUnfocus` (default: `true`): Hide the suggestions box when the `TextField` loses focus.\n\nOn the `SuggestionsController`:\n\n- `open(gainFocus: false)`: Show the suggestions box without focusing it.\n- `close(retainFocus: true)`: Hide the suggestions box without unfocusing it.\n\n### Customizing everything\n\nTo create your own version of the TypeAhead widget, that is neither Material nor Cupertino, you can use the `RawTypeAheadField` widget.\n\nYou must then specify the following parameters:\n\n- `builder` (to build the `TextField`)\n- `loadingBuilder` (to build the loading widget)\n- `errorBuilder` (to build the error widget)\n- `emptyBuilder` (to build the empty widget)\n- `itemBuilder` (to build the suggestions)\n\nAs well as all the usual parameters, such as `suggestionsCallback`, `onSelected`, etc.\n\nThe `decorationBuilder` can be used to inject required wrappers like `Material` or `DefaultTextStyle`.\nFor more information, see the source code of the `TypeAheadField` widget.\n\n## FAQ\n\n### My suggestions arent changing when I type\n\nYou have most likely forgotten to pass the controller and focus node to the `TextField` in the `builder` property.\nThis is required for the suggestions box to function. Here is an example:\n\n```dart\nTypeAheadField(\n  // ...\n  controller: myTextEditingController, // your custom controller, or null\n  builder: (context, controller, focusNode) {\n    return TextField(\n      controller: controller, // note how the controller is passed\n      focusNode: focusNode,\n      // ...\n    );\n  },\n);\n```\n\n### My suggestions are not updating when I click on the TextField\n\nThe TypeAhead field caches the suggestions to avoid unnecessary calls to the `suggestionsCallback`.\nIf you want to force the suggestions to update, you can use the `SuggestionsController` to force a refresh.\n\n```dart\nmySuggestionsController.refresh();\n```\n\n## Migrations\n\n### From 4.x to 5.x\n\nSince version 5.x, the package is based on Dart 3 (null-safety enforced). To use this package, please upgrade your Flutter SDK.\n\nAdditionally, various changes have been made to the API surface to make the package more flexible and customizable. The following changes have been made:\n\n- `SuggestionsBoxDecoration` has been removed. You can now directly wrap the `SuggestionsBox` with any widget you wish via the `decorationBuilder` property.\n- `TextFieldConfiguration` has been removed. You can now directly build your own custom `TextField` via the `builder` property.\n  Note that you must use the provided `controller` and `focusNode` properties, as they are required for the suggestions box to function.\n- `SuggestionsBoxController` has been renamed to `SuggestionsController`.\n- `CupertinoSuggestionsBoxController` has been merged into `SuggestionsController`.\n- `SuggestionsController` now holds the full state of the suggestions box, meaning suggestions, loading and error state. It will also send notifications when state changes occur.\n- `SuggestionsController` now offers streams for when a suggestion is selected.\n- `SuggestionsBox` should now automatically resize in all situations. Manual resize calls are no longer required.\n- `TypeAheadFormField` has been removed. You can use the `builder` property to build your own `TextFormField`.\n- Various parameters have been renamed to be shorter and more concise. Notable changes include:\n  - `suggestionsBoxController` -\u003e `suggestionsController`\n  - `layoutArchitecture` -\u003e `listBuilder`\n  - `noItemsFoundBuilder`-\u003e `emptyBuilder`\n  - `onSuggestionSelected` -\u003e `onSelected`\n  - `suggestionsBoxVerticalOffset` -\u003e `offset` (now also includes horizontal offset)\n  - `hideSuggestionsOnKeyboardHide` -\u003e `hideWithKeyboard`\n  - `keepSuggestionsOnSuggestionSelected` -\u003e `hideOnSelect` (inverted)\n  - `keepSuggestionsOnLoading`-\u003e `retainOnLoading`\n- Some parameters have been removed:\n  - `intercepting`: This is now always true, since it doesnt interfere on mobile platforms and generally has no downsides.\n  - `onSuggestionsBoxToggle`: You can subscribe to the `SuggestionsController` to get notified when the suggestions box is toggled.\n  - `ignoreAccessibleNavigation`: The new `Overlay` code no longer requires to act differently when accessibility is enabled.\n  - `minCharsForSuggestions`: You can return `null` from `suggestionsCallback` instead.\n  - `animationStart`: You can use the animation in the builder and map it to customise this.\n  - `autoFlipListDirection`: This is now always true. You can use the list builder to disable this behavior.\n  - `getImmediateSuggestions`: You can use the `debounceDuration` to achieve the same effect.\n\n### From 2.x to 3.x\n\nSince version 3.x, the package is based on Dart 2.12 (null-safety).\nFlutter now also features the inbuilt Autocomplete widget, which has similar behavior to this package.\n\n## For more information\n\nVisit the [API Documentation](https://pub.dartlang.org/documentation/flutter_typeahead/).\n\n## Team\n\n| [\u003cimg src=\"https://github.com/AbdulRahmanAlHamali.png\" width=\"100px;\"/\u003e](https://github.com/AbdulRahmanAlHamali) | [\u003cimg src=\"https://github.com/sjmcdowall.png\" width=\"100px;\"/\u003e](https://github.com/sjmcdowall) | [\u003cimg src=\"https://github.com/KaYBlitZ.png\" width=\"100px;\"/\u003e](https://github.com/KaYBlitZ) | [\u003cimg src=\"https://github.com/clragon.png\" width=\"100px;\"/\u003e](https://github.com/clragon) |\n| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |\n| AbdulRahman AlHamali                                                                                             | S McDowall                                                                                     | Kenneth Liang                                                                              | clragon                                                                                  |\n\n## Thank you\n\nThis project is the result of the collective effort of contributors who participated effectively by submitting pull requests, reporting issues, and answering questions.\nThank you for your proactiveness, and we hope `flutter_typeahead` made your lifes at least a little easier!\n\nIf you would like to contribute, please read the [Contribution Guidelines](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAbdulRahmanAlHamali%2Fflutter_typeahead","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAbdulRahmanAlHamali%2Fflutter_typeahead","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAbdulRahmanAlHamali%2Fflutter_typeahead/lists"}