Ever started typing into a search box and had it finish your thought before you even typed three letters? It feels effortless. But as Flutter developers, we know that building a smooth flutter search textfield with great suggestions takes a little extra care behind the scenes.
Whether you need a simple flutter autocomplete textfield for local static data or a powerful flutter autocomplete api setup that fetches remote data as you type, getting the search experience right is huge for user retention.
Nobody likes sluggish search bars or laggy text fields that hammer an API with every single keystroke.
In this deep dive, you will learn how to build production-ready flutter textfield suggestions from scratch. We will cover everything from basic local lists and search-as-you-type behavior to async network calls, request debouncing, custom UI overlays, and even flutter google places autocomplete.
Grab a cup of coffee, fire up your IDE, and let's turn your static inputs into smart, lightning-fast search fields!
Getting Started with the Built-in Autocomplete Widget
Before pulling in third-party packages, Flutter actually comes with a powerful, built-in widget specifically designed for this: the Autocomplete widget. It handles the heavy lifting of showing overlays, listening to user input, and filtering suggestions out of the box.
If you need a straightforward flutter autocomplete textfield using local static data, this is usually the best place to start.
Building a Local Search Field
Let’s look at a complete, working example. Here, we pass a static list of programming languages into the optionsBuilder callback. The widget automatically filters options based on what the user types into the flutter search textfield.
import 'package:flutter/material.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Autocomplete',
debugShowCheckedModeBanner: false,
theme: ThemeData(
useMaterial3: true,
colorSchemeSeed: Colors.blue,
brightness: Brightness.light,
),
home: const HomeScreen(),
);
}
}
class HomeScreen extends StatefulWidget {
const HomeScreen({super.key});
@override
State<HomeScreen> createState() => _HomeScreenState();
}
class _HomeScreenState extends State<HomeScreen> {
// Our static dataset for local filtering
static const List<String> _kOptions = <String>[
'Dart',
'Flutter',
'JavaScript',
'Python',
'Java',
'Kotlin',
'Swift',
'C++',
];
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Local Autocomplete')),
body: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
const Text('Search Programming Languages:'),
const SizedBox(height: 8),
// The core flutter autocomplete widget
Autocomplete<String>(
optionsBuilder: (TextEditingValue textEditingValue) {
// If the field is empty, don't show any suggestions
if (textEditingValue.text.isEmpty) {
return const Iterable<String>.empty();
}
// Filter local dataset using search-as-you-type logic
return _kOptions.where((String option) {
return option.toLowerCase().contains(
textEditingValue.text.toLowerCase(),
);
});
},
onSelected: (String selection) {
debugPrint('You selected: $selection');
},
),
],
),
),
);
}
}Key Takeaways
-
optionsBuilder: This function runs every time the text changes. It provides aTextEditingValuecontaining current input text and selection state. - Case-Insensitive Matching: Converting both the option and query to lowercase guarantees smooth flutter textfield suggestions even if users capitalize differently.
-
onSelected: Called immediately when a user taps a suggestion from the dropdown overlay list.
Ready to Go Beyond the Basics?
Learn Flutter the right way with 100+ practical lessons, real projects, and lifetime updates.
Building a Custom TextField with Suggestions
While the built-in Autocomplete widget works well for basic cases, you often need total visual and behavioral control over your input fields.
When you want custom dropdown positioning, tailored borders, floating badges, or specific animations, building a flutter textfield suggestions overlay manually using ComposedBox or OverlayPortal gives you unlimited flexibility.
Using an OverlayPortal (or Flutter’s traditional OverlayEntry) allows your suggestion list to float on top of other screen content without altering the main layout structure or getting clipped by parent widgets.
Building a Custom Overlay Suggestion Field
Here is a complete, working example that pairs a standard TextField with a custom floating overlay menu to deliver responsive flutter search textfield interactions.
class _HomeScreenState extends State<HomeScreen> {
final TextEditingController _controller = TextEditingController();
final FocusNode _focusNode = FocusNode();
final OverlayPortalController _overlayController = OverlayPortalController();
final LayerLink _layerLink = LayerLink();
static const List<String> _kCities = [
'Amsterdam',
'Austin',
'Bangkok',
'Barcelona',
'Berlin',
'Boston',
'Chicago',
'London',
'New York',
'Paris',
'Tokyo',
];
List<String> _filteredCities = [];
void _onTextChanged(String query) {
if (query.isEmpty) {
setState(() {
_filteredCities = [];
});
_overlayController.hide();
return;
}
final matches = _kCities.where((city) {
return city.toLowerCase().contains(query.toLowerCase());
}).toList();
setState(() {
_filteredCities = matches;
});
if (matches.isNotEmpty && !_overlayController.isShowing) {
_overlayController.show();
} else if (matches.isEmpty && _overlayController.isShowing) {
_overlayController.hide();
}
}
void _selectCity(String city) {
_controller.text = city;
setState(() {
_filteredCities = [];
});
_overlayController.hide();
_focusNode.unfocus();
}
void _clearText() {
_controller.clear();
setState(() {
_filteredCities = [];
});
_overlayController.hide();
}
@override
void dispose() {
_controller.dispose();
_focusNode.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
final colorScheme = Theme.of(context).colorScheme;
return Scaffold(
appBar: AppBar(title: const Text('Custom Suggestions Field')),
body: Padding(
padding: const EdgeInsets.all(16),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
const Text('Destination City:'),
const SizedBox(height: 8),
OverlayPortal(
controller: _overlayController,
overlayChildBuilder: (context) {
return CompositedTransformFollower(
link: _layerLink,
targetAnchor: Alignment.bottomLeft,
followerAnchor: Alignment.topLeft,
offset: const Offset(0, 4),
child: Align(
alignment: Alignment.topLeft,
child: Material(
elevation: 4,
color: colorScheme.surface,
shape: RoundedRectangleBorder(
borderRadius: BorderRadius.circular(8),
side: BorderSide(color: Theme.of(context).dividerColor),
),
clipBehavior: Clip.antiAlias,
child: SizedBox(
width: MediaQuery.of(context).size.width - 32,
child: ConstrainedBox(
constraints: const BoxConstraints(maxHeight: 200),
child: ListView.builder(
padding: EdgeInsets.zero,
shrinkWrap: true,
itemCount: _filteredCities.length,
itemBuilder: (context, index) {
final city = _filteredCities[index];
return ListTile(
leading: const Icon(Icons.location_city),
title: Text(city),
onTap: () {
_selectCity(city);
},
);
},
),
),
),
),
),
);
},
child: CompositedTransformTarget(
link: _layerLink,
child: TextField(
controller: _controller,
focusNode: _focusNode,
onChanged: _onTextChanged,
decoration: InputDecoration(
hintText: 'Type a city name...',
prefixIcon: const Icon(Icons.search),
suffixIcon: _controller.text.isNotEmpty
? IconButton(
icon: const Icon(Icons.clear),
onPressed: _clearText,
)
: null,
border: const OutlineInputBorder(),
),
),
),
),
],
),
),
);
}
}Key Highlights
-
OverlayPortalControl: Flutter 3.10+ introducedOverlayPortal, which simplifies managing custom overlay UI states without tedious manualOverlayEntrycreation. -
CompositedTransformFollower: Keeps the suggestion box perfectly glued beneath your flutter autocomplete textfield, even if your screen scrolls or resizes. - Clean Focus Handling: Closing the dropdown automatically on focus loss creates a clean experience for active users.
Mastering Search-as-You-Type Mechanics
Providing instant feedback as users type creates a fast, app-like experience.
However, a naive search-as-you-type implementation that fires network calls on every single keypress can quickly overwhelm your back-end server, exceed API rate limits, and degrade app performance.
To make flutter search textfield experiences feel instant while keeping network usage reasonable, you need to combine real-time input listening with request throttling mechanisms.
Building a Search-as-You-Type Filter with Reactive State
Here is a practical, runnable example demonstrating real-time filtering with instant visual feedback and clear empty states using standard Flutter state management.
class _HomeScreenState extends State<HomeScreen> {
final TextEditingController _searchController = TextEditingController();
// Mock dataset representing local database records
static const List<Map<String, String>> _kProducts = [
{'name': 'MacBook Pro 16"', 'category': 'Laptops'},
{'name': 'iPhone 15 Pro', 'category': 'Smartphones'},
{'name': 'iPad Air', 'category': 'Tablets'},
{'name': 'AirPods Pro', 'category': 'Audio'},
{'name': 'Apple Watch Ultra', 'category': 'Wearables'},
{'name': 'Mac Mini M2', 'category': 'Desktops'},
{'name': 'Studio Display', 'category': 'Monitors'},
];
List<Map<String, String>> _searchResults = [];
bool _isSearching = false;
@override
void initState() {
super.initState();
_searchResults = List.from(_kProducts);
}
void _onSearchChanged(String query) {
setState(() {
_isSearching = query.isNotEmpty;
if (query.isEmpty) {
_searchResults = List.from(_kProducts);
} else {
_searchResults = _kProducts.where((product) {
final nameMatch = product['name']!.toLowerCase().contains(
query.toLowerCase(),
);
final categoryMatch = product['category']!.toLowerCase().contains(
query.toLowerCase(),
);
return nameMatch || categoryMatch;
}).toList();
}
});
}
@override
void dispose() {
_searchController.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Real-Time Search-as-You-Type')),
body: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
children: [
// Standard Flutter textfield suggestions entry
TextField(
controller: _searchController,
onChanged: _onSearchChanged,
decoration: InputDecoration(
hintText: 'Search products or categories...',
prefixIcon: const Icon(Icons.search),
suffixIcon: _isSearching
? IconButton(
icon: const Icon(Icons.clear),
onPressed: () {
_searchController.clear();
_onSearchChanged('');
},
)
: null,
border: OutlineInputBorder(
borderRadius: BorderRadius.circular(12),
),
),
),
const SizedBox(height: 16),
Expanded(
child: _searchResults.isEmpty
? Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Icon(
Icons.search_off,
size: 48,
color: Theme.of(context).disabledColor,
),
const SizedBox(height: 8),
Text(
'No items match "${_searchController.text}"',
style: TextStyle(
color: Theme.of(context).disabledColor,
),
),
],
),
)
: ListView.separated(
itemCount: _searchResults.length,
separatorBuilder: (context, index) => const Divider(),
itemBuilder: (context, index) {
final item = _searchResults[index];
return ListTile(
leading: const Icon(Icons.shopping_bag_outlined),
title: Text(item['name']!),
subtitle: Text(item['category']!),
trailing: const Icon(
Icons.arrow_forward_ios,
size: 14,
),
onTap: () {
debugPrint('Selected product: ${item['name']}');
},
);
},
),
),
],
),
),
);
}
}Best Practices for Search-as-You-Type
- Multi-Field Matching: Looking up matches across product titles, categories, and tags yields far better flutter textfield suggestions than matching raw titles alone.
- Immediate Feedback: Clearing the input should restore default lists immediately to keep the UI feel snappy.
- Graceful Empty States: Always inform users when zero matches return instead of leaving them with a blank white screen.
Connecting to Remote Services with API Autocomplete
Local filtering works great when your data set is small and stays entirely on the device. But for huge catalogs, dynamic databases, or location services, you need an async search setup that fetches remote data over the network.
When wiring up a flutter autocomplete api endpoint, you need to gracefully handle asynchronous network calls, show clear loading indicators while waiting, and protect against out-of-order responses.
Building an Async API Search Field
Here is a complete, working example using Flutter's built-in Autocomplete widget connected to a simulated asynchronous backend API.
class _HomeScreenState extends State<HomeScreen> {
// Simulated REST API fetch that returns
// remote search suggestions.
Future<Iterable<String>> _fetchApiSuggestions(String query) async {
if (query.isEmpty) {
return const Iterable<String>.empty();
}
// Simulate network delay.
await Future.delayed(const Duration(milliseconds: 600));
// Mock response data from a backend server.
const mockRemoteDatabase = [
'Apple iPhone 15',
'Apple Watch Series 9',
'Asus ROG Phone',
'Google Pixel 8',
'Google Pixel Fold',
'Samsung Galaxy S24',
'Samsung Galaxy Z Flip',
'Sony Xperia 1',
];
return mockRemoteDatabase.where((item) {
return item.toLowerCase().contains(query.toLowerCase());
});
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('API Autocomplete')),
body: Padding(
padding: const EdgeInsets.all(16),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
const Text('Search Devices (Async API):'),
const SizedBox(height: 8),
Autocomplete<String>(
optionsBuilder: (TextEditingValue textEditingValue) async {
final suggestions = await _fetchApiSuggestions(
textEditingValue.text,
);
return suggestions;
},
optionsViewBuilder: (context, onSelected, options) {
return Align(
alignment: Alignment.topLeft,
child: Material(
elevation: 4,
color: Theme.of(context).colorScheme.surface,
shape: RoundedRectangleBorder(
borderRadius: BorderRadius.circular(8),
side: BorderSide(color: Theme.of(context).dividerColor),
),
clipBehavior: Clip.antiAlias,
child: SizedBox(
width: MediaQuery.of(context).size.width - 32,
child: ListView.builder(
padding: EdgeInsets.zero,
shrinkWrap: true,
itemCount: options.length,
itemBuilder: (BuildContext context, int index) {
final String option = options.elementAt(index);
return ListTile(
leading: const Icon(Icons.cloud_download_outlined),
title: Text(option),
onTap: () {
onSelected(option);
},
);
},
),
),
),
);
},
onSelected: (String selection) {
debugPrint('API item selected: $selection');
},
),
],
),
),
);
}
}Key Considerations for Remote Autocomplete
- Handling Network Latency: Providing feedback while fetching flutter textfield suggestions prevents users from assuming the input field is broken or frozen.
-
optionsViewBuilderCustomization: Overriding default view builders lets you style backend response dropdowns to match your app’s custom design system. - Optimizing Network Usage: Fetching from remote endpoints directly on every keystroke can get expensive fast. Combining asynchronous API logic with request debouncing is essential for production deployments.
Debouncing Requests for Better Performance
Now that your flutter autocomplete api setup can pull data from a remote server, there is a critical problem we need to fix: hitting your endpoint on every single keystroke.
If a user types "Flutter" quickly, that single word triggers 7 back-to-back network requests in less than two seconds! This wastes bandwidth, burns through server resources, costs money on paid API tier limits, and causes race conditions where older requests might arrive after newer ones.
The solution is debouncing API calls. Debouncing delays the network request until the user stops typing for a specific duration (like 300 to 500 milliseconds).
Implementing a Debounced Search Field
Here is a complete, working example using Dart's native Timer class to build a clean flutter debounce textfield without requiring any external packages.
class _HomeScreenState extends State<HomeScreen> {
final TextEditingController _controller = TextEditingController();
Timer? _debounceTimer;
bool _isLoading = false;
List<String> _apiResults = [];
int _networkCallCount = 0; // Tracks total API calls saved
// Simulated backend API endpoint
Future<List<String>> _searchRemoteApi(String query) async {
await Future.delayed(const Duration(milliseconds: 500));
const mockDatabase = [
'Clean Code by Robert C. Martin',
'Design Patterns by Gang of Four',
'Flutter in Action by Eric Windmill',
'Refactoring by Martin Fowler',
'The Pragmatic Programmer',
'You Don\'t Know JS by Kyle Simpson',
];
return mockDatabase
.where((book) => book.toLowerCase().contains(query.toLowerCase()))
.toList();
}
// Core debouncing logic
void _onSearchChanged(String query) {
// 1. Cancel the timer if the user types again before duration finishes
if (_debounceTimer?.isActive ?? false) {
_debounceTimer!.cancel();
}
if (query.isEmpty) {
setState(() {
_apiResults = [];
_isLoading = false;
});
return;
}
// 2. Start a new timer (e.g., 500ms delay)
_debounceTimer = Timer(const Duration(milliseconds: 500), () async {
setState(() {
_isLoading = true;
});
final results = await _searchRemoteApi(query);
if (mounted) {
setState(() {
_apiResults = results;
_isLoading = false;
_networkCallCount++;
});
}
});
}
@override
void dispose() {
_debounceTimer?.cancel();
_controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Debounced API Search')),
body: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
// Debounced flutter search textfield
TextField(
controller: _controller,
onChanged: _onSearchChanged,
decoration: InputDecoration(
hintText: 'Search programming books...',
prefixIcon: const Icon(Icons.search),
suffixIcon: _isLoading
? const Padding(
padding: EdgeInsets.all(12.0),
child: CircularProgressIndicator(strokeWidth: 2),
)
: _controller.text.isNotEmpty
? IconButton(
icon: const Icon(Icons.clear),
onPressed: () {
_controller.clear();
_onSearchChanged('');
},
)
: null,
border: OutlineInputBorder(
borderRadius: BorderRadius.circular(12),
),
),
),
const SizedBox(height: 12),
Text(
'API Requests Fired: $_networkCallCount',
style: TextStyle(
color: Theme.of(context).colorScheme.primary,
fontWeight: FontWeight.bold,
),
),
const SizedBox(height: 16),
Expanded(
child: _apiResults.isEmpty && !_isLoading
? Center(
child: Text(
_controller.text.isEmpty
? 'Type to trigger debounced API search'
: 'No books found',
style: TextStyle(
color: Theme.of(context).disabledColor,
),
),
)
: ListView.builder(
itemCount: _apiResults.length,
itemBuilder: (context, index) {
return Card(
margin: const EdgeInsets.symmetric(vertical: 4),
child: ListTile(
leading: const Icon(Icons.book),
title: Text(_apiResults[index]),
),
);
},
),
),
],
),
),
);
}
}Why Debouncing is Essential
- Massive Cost Savings: For paid billing models like flutter google places autocomplete, every request costs real money. Debouncing cuts unnecessary requests by up to 80%.
- Preventing Race Conditions: If a slow network request finishes after a faster, newer request, stale data overwrites your screen. A proper timer prevents old network calls from firing in the first place.
- Better User Experience: Pausing network operations while the user active types prevents jerky UI updates and saves mobile battery life.
Implementing Google Places Autocomplete
Location-based searches are one of the most common places you will need search suggestions.
Whether you are building a delivery app, ride-sharing service, or real estate portal, setting up a smooth flutter google places autocomplete experience is essential for converting address inputs into structured geographical data.
Because the Places API charges per request (or per autocomplete session), pairing your address search field with a debouncer and session tokens is mandatory to avoid huge API bills.
Building a Google Places Style Search Field
Here is a complete, working example simulating a flutter autocomplete api location search. It integrates address prediction data model structures, session token handling, and debounced location fetching within an async search workflow.
import 'dart:async';
import 'package:flutter/material.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Autocomplete',
debugShowCheckedModeBanner: false,
theme: ThemeData(
useMaterial3: true,
colorSchemeSeed: Colors.blue,
brightness: Brightness.light,
),
home: const HomeScreen(),
);
}
}
// Data model representing a Google Place Prediction
class PlacePrediction {
final String placeId;
final String mainText;
final String secondaryText;
PlacePrediction({
required this.placeId,
required this.mainText,
required this.secondaryText,
});
}
class HomeScreen extends StatefulWidget {
const HomeScreen({super.key});
@override
State<HomeScreen> createState() => _HomeScreenState();
}
class _HomeScreenState extends State<HomeScreen> {
final TextEditingController _addressController = TextEditingController();
Timer? _debounceTimer;
bool _isLoading = false;
List<PlacePrediction> _predictions = [];
@override
void initState() {
super.initState();
_resetSessionToken();
}
void _resetSessionToken() {
// Session tokens group prediction requests together for billing purposes
}
// Simulated Google Places API call
Future<List<PlacePrediction>> _fetchPlacePredictions(String input) async {
await Future.delayed(const Duration(milliseconds: 400));
if (input.isEmpty) return [];
// Mock response simulating Google Places Autocomplete payload
final mockPlaces = [
PlacePrediction(
placeId: '1',
mainText: '1600 Amphitheatre Parkway',
secondaryText: 'Mountain View, CA, USA',
),
PlacePrediction(
placeId: '2',
mainText: '10 Downing Street',
secondaryText: 'London, UK',
),
PlacePrediction(
placeId: '3',
mainText: '1 Infinite Loop',
secondaryText: 'Cupertino, CA, USA',
),
PlacePrediction(
placeId: '4',
mainText: 'Eiffel Tower',
secondaryText: 'Champ de Mars, Paris, France',
),
];
return mockPlaces
.where(
(place) =>
place.mainText.toLowerCase().contains(input.toLowerCase()) ||
place.secondaryText.toLowerCase().contains(input.toLowerCase()),
)
.toList();
}
void _onAddressChanged(String query) {
if (_debounceTimer?.isActive ?? false) {
_debounceTimer!.cancel();
}
if (query.isEmpty) {
setState(() {
_predictions = [];
_isLoading = false;
});
return;
}
// Debounce network request to save Google Places API quota
_debounceTimer = Timer(const Duration(milliseconds: 400), () async {
setState(() {
_isLoading = true;
});
final results = await _fetchPlacePredictions(query);
if (mounted) {
setState(() {
_predictions = results;
_isLoading = false;
});
}
});
}
void _onPlaceSelected(PlacePrediction prediction) {
_addressController.text =
'${prediction.mainText}, ${prediction.secondaryText}';
setState(() {
_predictions = [];
});
// Reset session token after a place selection is completed
_resetSessionToken();
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(
content: Text('Selected Place ID: ${prediction.placeId}'),
behavior: SnackBarBehavior.floating,
),
);
}
@override
void dispose() {
_debounceTimer?.cancel();
_addressController.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Google Places Search')),
body: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
// Optimized flutter search textfield for locations
TextField(
controller: _addressController,
onChanged: _onAddressChanged,
decoration: InputDecoration(
hintText: 'Enter street address or landmark...',
prefixIcon: const Icon(Icons.location_on_outlined),
suffixIcon: _isLoading
? const Padding(
padding: EdgeInsets.all(12.0),
child: CircularProgressIndicator(strokeWidth: 2),
)
: _addressController.text.isNotEmpty
? IconButton(
icon: const Icon(Icons.clear),
onPressed: () {
_addressController.clear();
_onAddressChanged('');
},
)
: null,
border: OutlineInputBorder(
borderRadius: BorderRadius.circular(12),
),
),
),
const SizedBox(height: 8),
// Suggestion list view
Expanded(
child: _predictions.isEmpty
? Center(
child: Text(
_addressController.text.isEmpty
? 'Start typing an address...'
: 'No location matches found',
style: TextStyle(
color: Theme.of(context).disabledColor,
),
),
)
: ListView.builder(
itemCount: _predictions.length,
itemBuilder: (context, index) {
final place = _predictions[index];
return Card(
elevation: 0,
color: Theme.of(context)
.colorScheme
.surfaceContainerHighest
.withOpacity(0.3),
margin: const EdgeInsets.symmetric(vertical: 4),
child: ListTile(
leading: const CircleAvatar(
child: Icon(Icons.pin_drop, size: 18),
),
title: Text(
place.mainText,
style: const TextStyle(
fontWeight: FontWeight.bold,
),
),
subtitle: Text(place.secondaryText),
onTap: () => _onPlaceSelected(place),
),
);
},
),
),
],
),
),
);
}
}Critical Rules for Production Places Autocomplete
- Session Tokens: Always pass a unique UUID session token when requesting place predictions. Google bills a full session (prediction lookups + final details fetch) as a single unit instead of billing per individual prediction call.
- Debounce Thresholds: Set your flutter debounce textfield timer between 350ms and 500ms to balance responsiveness with request optimization.
- Structured Display: Split place responses into primary text (building/street) and secondary text (city/country) so users can scan suggestions easily.
Take Your Flutter Skills to the Next Level
Build professional Flutter apps through structured lessons, practical projects, and a complete capstone.
Creating Custom Suggestion Lists for Rich Search Results
Standard text-only drop-downs are great for quick selections, but modern apps often require richer search experiences.
A production-ready flutter search textfield frequently needs custom layouts that render thumbnails, category tags, pricing badges, or action buttons right inside the suggestion list.
By building custom suggestion item UI builders, you can transform plain text results into an engaging discovery experience.
Building Rich Suggestion Cards with Custom Widgets
Here is a complete, working example that displays rich product metadata—including images, prices, categories, and stock status—inside custom flutter textfield suggestions.
import 'package:flutter/material.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Autocomplete',
debugShowCheckedModeBanner: false,
theme: ThemeData(
useMaterial3: true,
colorSchemeSeed: Colors.blue,
brightness: Brightness.light,
),
home: const HomeScreen(),
);
}
}
// Data model representing a rich product item.
class SearchProduct {
final String title;
final String category;
final double price;
final bool inStock;
final IconData icon;
const SearchProduct({
required this.title,
required this.category,
required this.price,
required this.inStock,
required this.icon,
});
}
class HomeScreen extends StatefulWidget {
const HomeScreen({super.key});
@override
State<HomeScreen> createState() => _HomeScreenState();
}
class _HomeScreenState extends State<HomeScreen> {
static const List<SearchProduct> _kCatalog = [
SearchProduct(
title: 'Wireless Noise-Canceling Headphones',
category: 'Electronics',
price: 299.99,
inStock: true,
icon: Icons.headphones,
),
SearchProduct(
title: 'Ergonomic Mechanical Keyboard',
category: 'Accessories',
price: 149.50,
inStock: true,
icon: Icons.keyboard,
),
SearchProduct(
title: 'Ultra-Wide Curved Monitor 34"',
category: 'Displays',
price: 599.00,
inStock: false,
icon: Icons.monitor,
),
SearchProduct(
title: 'Smart Fitness Watch Series 5',
category: 'Wearables',
price: 199.99,
inStock: true,
icon: Icons.watch,
),
];
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Custom Suggestion List')),
body: Padding(
padding: const EdgeInsets.all(16),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
const Text('Search Product Catalog:'),
const SizedBox(height: 8),
Autocomplete<SearchProduct>(
// Determines what gets displayed in the
// TextField after an item is selected.
displayStringForOption: (SearchProduct option) {
return option.title;
},
// Filters the catalog based on the
// user's search query.
optionsBuilder: (TextEditingValue textEditingValue) {
if (textEditingValue.text.isEmpty) {
return const Iterable<SearchProduct>.empty();
}
final query = textEditingValue.text.toLowerCase();
return _kCatalog.where((SearchProduct item) {
return item.title.toLowerCase().contains(query) ||
item.category.toLowerCase().contains(query);
});
},
// Builds the custom suggestion overlay.
optionsViewBuilder: (context, onSelected, options) {
return Align(
alignment: Alignment.topLeft,
child: Material(
elevation: 6,
// Let Material own the background color.
color: Theme.of(context).colorScheme.surface,
// Let Material own the rounded corners
// and border.
shape: RoundedRectangleBorder(
borderRadius: BorderRadius.circular(12),
side: BorderSide(color: Theme.of(context).dividerColor),
),
// Clips ListTile ink effects to the
// rounded shape.
clipBehavior: Clip.antiAlias,
child: SizedBox(
width: MediaQuery.of(context).size.width - 32,
child: ConstrainedBox(
constraints: const BoxConstraints(maxHeight: 320),
child: ListView.separated(
padding: const EdgeInsets.symmetric(vertical: 8),
shrinkWrap: true,
itemCount: options.length,
separatorBuilder: (context, index) {
return const Divider(height: 1);
},
itemBuilder: (BuildContext context, int index) {
final SearchProduct product = options.elementAt(
index,
);
return ListTile(
// Product icon.
leading: CircleAvatar(
backgroundColor: Theme.of(
context,
).colorScheme.primaryContainer,
child: Icon(
product.icon,
color: Theme.of(
context,
).colorScheme.onPrimaryContainer,
),
),
// Product name.
title: Text(
product.title,
style: const TextStyle(
fontWeight: FontWeight.w600,
),
),
// Category + price.
subtitle: Row(
children: [
Container(
padding: const EdgeInsets.symmetric(
horizontal: 6,
vertical: 2,
),
decoration: BoxDecoration(
color: Theme.of(
context,
).colorScheme.surfaceContainerHighest,
borderRadius: BorderRadius.circular(4),
),
child: Text(
product.category,
style: const TextStyle(fontSize: 11),
),
),
const SizedBox(width: 8),
Text(
'\$${product.price.toStringAsFixed(2)}',
style: const TextStyle(
fontWeight: FontWeight.bold,
color: Colors.green,
),
),
],
),
// Stock status.
trailing: product.inStock
? const Chip(
label: Text(
'In Stock',
style: TextStyle(
fontSize: 10,
color: Colors.white,
),
),
backgroundColor: Colors.green,
visualDensity: VisualDensity.compact,
)
: const Chip(
label: Text(
'Out of Stock',
style: TextStyle(
fontSize: 10,
color: Colors.white,
),
),
backgroundColor: Colors.grey,
visualDensity: VisualDensity.compact,
),
// Tell Autocomplete which
// product was selected.
onTap: () {
onSelected(product);
},
);
},
),
),
),
),
);
},
// Called after the user selects a product.
onSelected: (SearchProduct selection) {
debugPrint(
'User selected product: '
'${selection.title}',
);
},
),
],
),
),
);
}
}Key UI Features for Custom Suggestion Lists
-
displayStringForOption: Maps complex model objects back into readable string values for the text input controller once a selection occurs. - Visual Hierarchy: Using clear prices, categories, and availability chips makes dynamic flutter textfield suggestions much easier for users to evaluate quickly.
-
Structured Constraints: Wrapping your list in explicit
BoxConstraintsensures that large result sets scroll smoothly inside the overlay container.
Managing Asynchronous Search States and Race Conditions
When dealing with real-time API integrations, robust async search handling requires more than just making a future request.
As users type, edit, or delete characters quickly, multiple asynchronous network requests are dispatched in rapid succession.
If a response from an earlier request takes longer to return than a subsequent request, an out-of-order response (a race condition) can overwrite fresh results with stale data.
Mastering async search means managing pending states, handling network failures, and ensuring that late-arriving responses are discarded cleanly.
Handling Async Search with Active State Tracking
Here is a complete, working example demonstrating robust state handling for a flutter autocomplete api field. It uses request tokens to ignore outdated network responses and shows full loading, error, and empty states.
import 'dart:async';
import 'package:flutter/material.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Autocomplete',
debugShowCheckedModeBanner: false,
theme: ThemeData(
useMaterial3: true,
colorSchemeSeed: Colors.blue,
brightness: Brightness.light,
),
home: const HomeScreen(),
);
}
}
class HomeScreen extends StatefulWidget {
const HomeScreen({super.key});
@override
State<HomeScreen> createState() => _HomeScreenState();
}
class _HomeScreenState extends State<HomeScreen> {
final TextEditingController _searchController = TextEditingController();
Timer? _debounceTimer;
bool _isLoading = false;
String? _errorMessage;
List<String> _results = [];
// Identifies the latest search request.
// Used to prevent stale responses from older
// requests from updating the UI.
int _activeRequestId = 0;
// Simulated asynchronous network request.
Future<List<String>> _fetchRemoteData(String query) async {
// Simulate network latency.
await Future.delayed(
Duration(milliseconds: 400 + (query.length % 3) * 200),
);
// Simulate a server error.
if (query.toLowerCase() == 'error') {
throw Exception('Server unreachable. Please check your network.');
}
// Simulated backend database.
const database = [
'Reactive Programming with Dart',
'Flutter State Management Guide',
'Asynchronous Programming in Dart',
'Building REST APIs with Node.js',
'GraphQL vs REST API Performance',
];
// Filter the simulated database.
return database
.where((item) => item.toLowerCase().contains(query.toLowerCase()))
.toList();
}
void _onSearchQueryChanged(String query) {
// Cancel the previous debounce timer.
if (_debounceTimer?.isActive ?? false) {
_debounceTimer!.cancel();
}
// Every new query makes previous requests stale.
final currentRequestId = ++_activeRequestId;
// Clear the UI when the search field is empty.
if (query.trim().isEmpty) {
setState(() {
_results = [];
_isLoading = false;
_errorMessage = null;
});
return;
}
// Wait until the user stops typing.
_debounceTimer = Timer(const Duration(milliseconds: 350), () async {
if (!mounted) return;
// The actual request is starting now.
setState(() {
_isLoading = true;
_errorMessage = null;
});
try {
final fetchedResults = await _fetchRemoteData(query);
// Ignore the response if a newer search
// has already been started.
if (currentRequestId != _activeRequestId) {
return;
}
if (!mounted) return;
setState(() {
_results = fetchedResults;
_isLoading = false;
});
} catch (e) {
// Ignore errors from old requests.
if (currentRequestId != _activeRequestId) {
return;
}
if (!mounted) return;
setState(() {
_errorMessage = e.toString().replaceAll('Exception: ', '');
_isLoading = false;
_results = [];
});
}
});
}
void _clearSearch() {
// Cancel any pending debounce.
if (_debounceTimer?.isActive ?? false) {
_debounceTimer!.cancel();
}
// Invalidate any request currently in flight.
_activeRequestId++;
_searchController.clear();
setState(() {
_results = [];
_isLoading = false;
_errorMessage = null;
});
}
@override
void dispose() {
_debounceTimer?.cancel();
_searchController.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Async Search State Control')),
body: Padding(
padding: const EdgeInsets.all(16),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
// Search field.
TextField(
controller: _searchController,
onChanged: _onSearchQueryChanged,
decoration: InputDecoration(
hintText: 'Type to search (type "error" to test failure)...',
prefixIcon: const Icon(Icons.search),
suffixIcon: _isLoading
? const Padding(
padding: EdgeInsets.all(12),
child: CircularProgressIndicator(strokeWidth: 2),
)
: _searchController.text.isNotEmpty
? IconButton(
icon: const Icon(Icons.clear),
onPressed: _clearSearch,
)
: null,
border: OutlineInputBorder(
borderRadius: BorderRadius.circular(12),
),
),
),
const SizedBox(height: 16),
// Dynamic result area.
Expanded(
child: Builder(
builder: (context) {
// Loading state.
if (_isLoading) {
return const Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
CircularProgressIndicator(),
SizedBox(height: 12),
Text('Fetching suggestions from server...'),
],
),
);
}
// Error state.
if (_errorMessage != null) {
return Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
const Icon(
Icons.error_outline,
size: 48,
color: Colors.red,
),
const SizedBox(height: 8),
Text(
_errorMessage!,
style: const TextStyle(color: Colors.red),
textAlign: TextAlign.center,
),
],
),
);
}
// Empty state.
if (_results.isEmpty) {
return Center(
child: Text(
_searchController.text.isEmpty
? 'Enter a query to trigger async search'
: 'No matching records found',
style: TextStyle(
color: Theme.of(context).disabledColor,
),
),
);
}
// Results state.
return ListView.builder(
itemCount: _results.length,
itemBuilder: (context, index) {
return Card(
margin: const EdgeInsets.symmetric(vertical: 4),
child: ListTile(
leading: const Icon(Icons.article_outlined),
title: Text(_results[index]),
trailing: const Icon(Icons.chevron_right),
),
);
},
);
},
),
),
],
),
),
);
}
}Key Strategies for Robust Async Search
-
Request Sequence Tokens: Incrementing an integer counter (
_activeRequestId) before each request ensures you ignore results from outdated requests that return out of order. - Explicit State Feedback: Inform users clearly whether the input is idle, fetching over the network, displaying zero matches, or recovering from a network exception.
-
Mounted Safeguards: Always check
if (mounted)after asynchronousawaitcalls to avoid callingsetState()on unmounted widget trees.
Highlighting Matches for a Polished UI
Adding visual highlights to matching text inside your search suggestions is one of those small design details that makes an app feel instantly more professional.
When users see the exact characters they typed highlighted in bold or vibrant colors, it reassures them that your flutter search textfield understands their intent.
Instead of displaying plain text strings, you can use Flutter's RichText and TextSpan widgets to dynamically break up strings into matching and non-matching segments.
Building a Match-Highlighting Suggestion Item
Here is a complete, working example that parses user queries in real-time and applies styled highlights directly inside your flutter textfield suggestions.
import 'package:flutter/material.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Highlighting Search Matches',
debugShowCheckedModeBanner: false,
theme: ThemeData(
useMaterial3: true,
colorSchemeSeed: Colors.blue,
brightness: Brightness.light,
),
home: const HomeScreen(),
);
}
}
class HomeScreen extends StatefulWidget {
const HomeScreen({super.key});
@override
State<HomeScreen> createState() => _HomeScreenState();
}
class _HomeScreenState extends State<HomeScreen> {
static const List<String> _kFrameworks = [
'Flutter Framework',
'Flutter for Web',
'Flutter Desktop Apps',
'React Native Cross-Platform',
'Android Jetpack Compose',
'iOS SwiftUI Development',
];
final TextEditingController _controller = TextEditingController();
final FocusNode _focusNode = FocusNode();
@override
void dispose() {
_controller.dispose();
_focusNode.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Highlight Search Matches')),
body: Padding(
padding: const EdgeInsets.all(16),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
const Text(
'Search Frameworks:',
style: TextStyle(fontWeight: FontWeight.bold),
),
const SizedBox(height: 8),
RawAutocomplete<String>(
// RawAutocomplete requires the controller
// and focus node to be supplied together.
textEditingController: _controller,
focusNode: _focusNode,
optionsBuilder: (TextEditingValue textEditingValue) {
if (textEditingValue.text.isEmpty) {
return const Iterable<String>.empty();
}
final query = textEditingValue.text.toLowerCase();
return _kFrameworks.where((option) {
return option.toLowerCase().contains(query);
});
},
fieldViewBuilder:
(
BuildContext context,
TextEditingController controller,
FocusNode focusNode,
VoidCallback onFieldSubmitted,
) {
return TextField(
controller: controller,
focusNode: focusNode,
onSubmitted: (_) {
onFieldSubmitted();
},
decoration: InputDecoration(
hintText: 'Type a framework...',
prefixIcon: const Icon(Icons.search),
border: OutlineInputBorder(
borderRadius: BorderRadius.circular(10),
),
),
);
},
optionsViewBuilder:
(
BuildContext context,
AutocompleteOnSelected<String> onSelected,
Iterable<String> options,
) {
final query = _controller.text;
final optionCount = options.length;
// Each ListTile is approximately 56px tall.
// The panel grows with the number of
// results but stops at 300px.
final suggestionHeight = (optionCount * 56.0).clamp(
0.0,
300.0,
);
return Align(
alignment: Alignment.topLeft,
child: Material(
elevation: 4,
// Material owns the background.
color: Theme.of(context).colorScheme.surface,
// Material owns the rounded shape.
shape: RoundedRectangleBorder(
borderRadius: BorderRadius.circular(10),
side: BorderSide(
color: Theme.of(context).dividerColor,
),
),
clipBehavior: Clip.antiAlias,
child: SizedBox(
width: MediaQuery.of(context).size.width - 32,
height: suggestionHeight,
child: ListView.builder(
padding: EdgeInsets.zero,
itemCount: optionCount,
itemBuilder: (BuildContext context, int index) {
final option = options.elementAt(index);
return ListTile(
leading: const Icon(Icons.saved_search),
title: HighlightedText(
text: option,
query: query,
highlightStyle: TextStyle(
fontWeight: FontWeight.bold,
color: Theme.of(
context,
).colorScheme.primary,
backgroundColor: Theme.of(context)
.colorScheme
.primaryContainer
.withValues(alpha: 0.5),
),
),
onTap: () {
onSelected(option);
},
);
},
),
),
),
);
},
onSelected: (String selection) {
debugPrint('Selected item: $selection');
},
),
],
),
),
);
}
}
// Highlights matching portions of text.
class HighlightedText extends StatelessWidget {
final String text;
final String query;
final TextStyle highlightStyle;
final TextStyle? normalStyle;
const HighlightedText({
super.key,
required this.text,
required this.query,
required this.highlightStyle,
this.normalStyle,
});
@override
Widget build(BuildContext context) {
if (query.isEmpty) {
return Text(text, style: normalStyle);
}
final List<TextSpan> spans = [];
final String lowerText = text.toLowerCase();
final String lowerQuery = query.toLowerCase();
int start = 0;
int indexOfMatch = lowerText.indexOf(lowerQuery, start);
while (indexOfMatch != -1) {
// Text before the match.
if (indexOfMatch > start) {
spans.add(
TextSpan(
text: text.substring(start, indexOfMatch),
style: normalStyle,
),
);
}
// Matching text.
spans.add(
TextSpan(
text: text.substring(indexOfMatch, indexOfMatch + query.length),
style: highlightStyle,
),
);
start = indexOfMatch + query.length;
indexOfMatch = lowerText.indexOf(lowerQuery, start);
}
// Remaining text.
if (start < text.length) {
spans.add(TextSpan(text: text.substring(start), style: normalStyle));
}
return RichText(
text: TextSpan(
style: normalStyle ?? DefaultTextStyle.of(context).style,
children: spans,
),
);
}
}Why Highlighted Matches Matter
- Instant Clarity: Users immediately see why a particular item appeared in their flutter textfield suggestions, reducing search friction.
- Enhanced Accessibility: Pairing bolding with subtle background pill colors makes target keywords jump off the screen effortlessly.
-
Flexible Substring Matching: Breaking inputs into structured
TextSpanlists handles mid-word matches, prefix matches, and multi-word queries with equal precision.
Elevate Your Search UX
Building high-performance search controls is a hallmark of great Flutter applications.
From simple static drop-downs to high-throughput async search fields, mastering local filtering, overlay positioning, flutter debounce textfield mechanics, and flutter google places autocomplete gives you everything you need to create delightful user experiences.
Ready to Build Professional Flutter Apps?
Turn today’s knowledge into real-world Flutter skills with Flutter Foundations.
Top comments (0)