Module 2
Topic 7
Search
Implementing efficient search functionality — from local filtering to real-time API search with debouncing.
What Is Search?
Search allows users to find specific items within a dataset by typing a query. It's essential for apps with large amounts of data, such as:
- E-commerce apps (search for products)
- Social media apps (search for users or posts)
- Messaging apps (search for messages or contacts)
- Content apps (search for articles or videos)
🎯 Two Approaches
- Local Search – Search within data already loaded in the app
- API Search – Send the search query to a server and get results
Search Strategies
There are three main search strategies used in Flutter apps:
Local Filtering
Filter already-loaded data in memory
API Search
Send query to server for results
Real-Time Search
Search as you type (with debouncing)
Local Search (Filtering)
Local search filters data that's already loaded in memory. It's fast and works offline.
lib/local_search_screen.dart – Local Filtering
import
'package:flutter/material.dart'
;
class
LocalSearchScreen
extends
StatefulWidget {
@override
State<LocalSearchScreen>
createState
() => _LocalSearchScreenState();
}
class
_LocalSearchScreenState
extends
State<LocalSearchScreen> {
final
List<String> _allItems = [
'Apple'
,
'Banana'
,
'Cherry'
,
'Date'
,
'Elderberry'
,
'Fig'
,
'Grape'
,
'Honeydew'
,
'Kiwi'
,
'Lemon'
,
'Mango'
,
'Nectarine'
,
'Orange'
,
'Papaya'
,
'Quince'
,
];
List<String> _filteredItems = [];
final
TextEditingController _searchController = TextEditingController();
@override
void
initState
() {
super
.initState();
_filteredItems = _allItems;
_searchController.addListener(_filterItems);
}
@override
void
dispose
() {
_searchController.removeListener(_filterItems);
_searchController.dispose();
super
.dispose();
}
void
_filterItems
() {
final
query = _searchController.text.toLowerCase().trim();
setState(() {
if
(query.isEmpty) {
_filteredItems = _allItems;
}
else
{
_filteredItems = _allItems
.where((item) => item.toLowerCase().contains(query))
.toList();
}
});
}
void
_clearSearch
() {
_searchController.clear();
setState(() {
_filteredItems = _allItems;
});
}
@override
Widget
build
(BuildContext context) {
return
Scaffold(
appBar: AppBar(
title: Text(
'Local Search'
),
centerTitle:
true
,
),
body: Column(
children: [
// Search Bar
Padding(
padding: EdgeInsets.all(
16
),
child: TextField(
controller: _searchController,
decoration: InputDecoration(
hintText:
'Search fruits...'
,
prefixIcon: Icon(Icons.search),
suffixIcon: _searchController.text.isNotEmpty
? IconButton(
icon: Icon(Icons.clear),
onPressed: _clearSearch,
)
:
null
,
border: OutlineInputBorder(
borderRadius: BorderRadius.circular(
12
),
),
filled:
true
,
fillColor: Colors.grey.shade50,
),
),
),
// Results count
Padding(
padding: EdgeInsets.symmetric(horizontal:
16
),
child: Row(
mainAxisAlignment: MainAxisAlignment.spaceBetween,
children: [
Text(
'${_filteredItems.length} items'
,
style: TextStyle(color: Colors.grey.shade600),
),
if
(_searchController.text.isNotEmpty)
TextButton(
onPressed: _clearSearch,
child: Text(
'Clear'
),
),
],
),
),
Expanded(
child: _filteredItems.isEmpty
? Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Icon(
Icons.search_off,
size:
64
,
color: Colors.grey.shade400,
),
SizedBox(height:
16
),
Text(
'No results found'
,
style: TextStyle(
fontSize:
18
,
color: Colors.grey.shade600,
),
),
SizedBox(height:
8
),
Text(
'Try a different search term'
,
style: TextStyle(color: Colors.grey.shade400),
),
],
),
)
: ListView.builder(
itemCount: _filteredItems.length,
itemBuilder: (context, index) {
final
item = _filteredItems[index];
return
ListTile(
leading: CircleAvatar(
child: Text(item[
0
]),
),
title: Text(item),
trailing: Icon(Icons.arrow_forward_ios, size:
16
),
);
},
),
),
],
),
);
}
}
✅ When to Use Local Search
- Small to medium datasets (under 10,000 items)
- Data is already loaded in memory
- Need offline search capability
- Simple filtering by text
API Search
API search sends the search query to a server and displays the results. This is necessary for large datasets.
lib/api_search_service.dart – Search Service
import
'dart:convert'
;
import
'package:http/http.dart'
as
http;
class
SearchService
{
final
http.Client client;
SearchService
({http.Client? client}) : client = client ?? http.Client();
Future
<List<dynamic>>
search
(String query) async {
if
(query.isEmpty)
return
[];
final
response = await client.get(
Uri.parse(
'https://jsonplaceholder.typicode.com/posts?q=${Uri.encodeComponent(query)}'
,
),
headers: {
'Accept'
:
'application/json'
},
);
if
(response.statusCode ==
200
) {
return
jsonDecode(response.body)
as
List<dynamic>;
}
else
{
throw
Exception(
'Search failed: ${response.statusCode}'
);
}
}
}
lib/api_search_screen.dart – API Search UI
import
'package:flutter/material.dart'
;
import
'api_search_service.dart'
;
class
ApiSearchScreen
extends
StatefulWidget {
@override
State<ApiSearchScreen>
createState
() => _ApiSearchScreenState();
}
class
_ApiSearchScreenState
extends
State<ApiSearchScreen> {
final
SearchService _searchService = SearchService();
final
TextEditingController _searchController = TextEditingController();
List<dynamic> _results = [];
bool
_isLoading =
false
;
bool
_hasSearched =
false
;
bool
_hasError =
false
;
String? _errorMessage;
Future
<
void
>
_performSearch
() async {
final
query = _searchController.text.trim();
if
(query.isEmpty) {
setState(() {
_results = [];
_hasSearched =
false
;
});
return
;
}
setState(() {
_isLoading =
true
;
_hasError =
false
;
_errorMessage =
null
;
_hasSearched =
true
;
});
try
{
final
results = await _searchService.search(query);
setState(() {
_results = results;
_isLoading =
false
;
});
}
catch
(e) {
setState(() {
_isLoading =
false
;
_hasError =
true
;
_errorMessage = e.toString();
});
}
}
void
_clearSearch
() {
_searchController.clear();
setState(() {
_results = [];
_hasSearched =
false
;
_hasError =
false
;
});
}
@override
Widget
build
(BuildContext context) {
return
Scaffold(
appBar: AppBar(
title: Text(
'API Search'
),
centerTitle:
true
,
),
body: Column(
children: [
// Search Bar
Padding(
padding: EdgeInsets.all(
16
),
child: Row(
children: [
Expanded(
child: TextField(
controller: _searchController,
decoration: InputDecoration(
hintText:
'Search posts...'
,
prefixIcon: Icon(Icons.search),
suffixIcon: _searchController.text.isNotEmpty
? IconButton(
icon: Icon(Icons.clear),
onPressed: _clearSearch,
)
:
null
,
border: OutlineInputBorder(
borderRadius: BorderRadius.circular(
12
),
),
filled:
true
,
fillColor: Colors.grey.shade50,
),
onSubmitted: (_) => _performSearch(),
),
),
SizedBox(width:
8
),
ElevatedButton(
onPressed: _isLoading ?
null
: _performSearch,
child: _isLoading
? SizedBox(
width:
20
,
height:
20
,
child: CircularProgressIndicator(
strokeWidth:
2
,
color: Colors.white,
),
)
: Icon(Icons.search),
),
],
),
),
// Results
Expanded(
child: _buildContent(),
),
],
),
);
}
Widget
_buildContent
() {
if
(_isLoading) {
return
Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
CircularProgressIndicator(),
SizedBox(height:
16
),
Text(
'Searching...'
),
],
),
);
}
if
(_hasError) {
return
Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Icon(Icons.error, size:
64
, color: Colors.red),
SizedBox(height:
16
),
Text(_errorMessage ??
'Search failed'
),
SizedBox(height:
16
),
ElevatedButton(
onPressed: _performSearch,
child: Text(
'Retry'
),
),
],
),
);
}
if
(!_hasSearched) {
return
Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Icon(Icons.search, size:
64
, color: Colors.grey.shade400),
SizedBox(height:
16
),
Text(
'Search for posts'
,
style: TextStyle(fontSize:
18
, color: Colors.grey.shade600),
),
Text(
'Enter a keyword to start searching'
,
style: TextStyle(color: Colors.grey.shade400),
),
],
),
);
}
if
(_results.isEmpty) {
return
Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Icon(Icons.search_off, size:
64
, color: Colors.grey.shade400),
SizedBox(height:
16
),
Text(
'No results found'
,
style: TextStyle(fontSize:
18
, color: Colors.grey.shade600),
),
Text(
'Try a different search term'
,
style: TextStyle(color: Colors.grey.shade400),
),
],
),
);
}
return
ListView.builder(
itemCount: _results.length,
itemBuilder: (context, index) {
final
item = _results[index];
return
Card(
margin: EdgeInsets.symmetric(horizontal:
16
, vertical:
4
),
child: ListTile(
title: Text(item[
'title'
] ??
'No title'
),
subtitle: Text(
item[
'body'
] ??
'No body'
,
maxLines:
2
,
overflow: TextOverflow.ellipsis,
),
leading: CircleAvatar(
child: Text((index +
1
).toString()),
),
),
);
},
);
}
}
Debouncing: Search as You Type
Debouncing prevents making an API call on every keystroke. Instead, it waits for the user to stop typing (e.g., 500ms) before performing the search.
⚡ Why Debounce?
- Prevents unnecessary API calls
- Reduces server load
- Improves performance and battery life
- Better user experience (no constant loading)
lib/debounced_search_screen.dart – With Debouncing
import
'dart:async'
;
import
'package:flutter/material.dart'
;
import
'api_search_service.dart'
;
class
DebouncedSearchScreen
extends
StatefulWidget {
@override
State<DebouncedSearchScreen>
createState
() => _DebouncedSearchScreenState();
}
class
_DebouncedSearchScreenState
extends
State<DebouncedSearchScreen> {
final
SearchService _searchService = SearchService();
final
TextEditingController _searchController = TextEditingController();
Timer? _debounceTimer;
List<dynamic> _results = [];
bool
_isLoading =
false
;
bool
_hasSearched =
false
;
bool
_hasError =
false
;
String? _errorMessage;
static
const
Duration debounceDelay = Duration(milliseconds:
500
);
@override
void
initState
() {
super
.initState();
_searchController.addListener(_onSearchChanged);
}
@override
void
dispose
() {
_debounceTimer?.cancel();
_searchController.removeListener(_onSearchChanged);
_searchController.dispose();
super
.dispose();
}
void
_onSearchChanged
() {
// Cancel the previous timer
_debounceTimer?.cancel();
// Start a new timer
_debounceTimer = Timer(debounceDelay, () {
_performSearch();
});
}
Future
<
void
>
_performSearch
() async {
final
query = _searchController.text.trim();
// Don't search for empty queries
if
(query.isEmpty) {
setState(() {
_results = [];
_hasSearched =
false
;
_isLoading =
false
;
});
return
;
}
setState(() {
_isLoading =
true
;
_hasError =
false
;
_errorMessage =
null
;
_hasSearched =
true
;
});
try
{
final
results = await _searchService.search(query);
setState(() {
_results = results;
_isLoading =
false
;
});
}
catch
(e) {
setState(() {
_isLoading =
false
;
_hasError =
true
;
_errorMessage = e.toString();
});
}
}
void
_clearSearch
() {
_debounceTimer?.cancel();
_searchController.clear();
setState(() {
_results = [];
_hasSearched =
false
;
_hasError =
false
;
_isLoading =
false
;
});
}
@override
Widget
build
(BuildContext context) {
return
Scaffold(
appBar: AppBar(
title: Text(
'Debounced Search'
),
centerTitle:
true
,
),
body: Column(
children: [
// Search Bar
Padding(
padding: EdgeInsets.all(
16
),
child: TextField(
controller: _searchController,
decoration: InputDecoration(
hintText:
'Type to search...'
,
prefixIcon: Icon(Icons.search),
suffixIcon: _searchController.text.isNotEmpty
? IconButton(
icon: Icon(Icons.clear),
onPressed: _clearSearch,
)
:
null
,
border: OutlineInputBorder(
borderRadius: BorderRadius.circular(
12
),
),
filled:
true
,
fillColor: Colors.grey.shade50,
),
),
),
// Status bar
Padding(
padding: EdgeInsets.symmetric(horizontal:
16
),
child: Row(
mainAxisAlignment: MainAxisAlignment.spaceBetween,
children: [
Text(
_isLoading
?
'Searching...'
: _hasSearched
?
'${_results.length} results'
:
'Type to search'
,
style: TextStyle(color: Colors.grey.shade600),
),
if
(_searchController.text.isNotEmpty)
Text(
'⌛ ${debounceDelay.inMilliseconds}ms delay'
,
style: TextStyle(
fontSize:
12
,
color: Colors.grey.shade400,
),
),
],
),
),
Expanded(
child: _buildContent(),
),
],
),
);
}
Widget
_buildContent
() {
// Show loading indicator while debouncing
if
(_isLoading) {
return
Center(child: CircularProgressIndicator());
}
if
(_hasError) {
return
Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Icon(Icons.error, size:
64
, color: Colors.red),
SizedBox(height:
16
),
Text(_errorMessage ??
'Search failed'
),
SizedBox(height:
16
),
ElevatedButton(
onPressed: _performSearch,
child: Text(
'Retry'
),
),
],
),
);
}
if
(!_hasSearched) {
return
Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Icon(Icons.search, size:
64
, color: Colors.grey.shade400),
SizedBox(height:
16
),
Text(
'Start typing to search'
,
style: TextStyle(fontSize:
18
, color: Colors.grey.shade600),
),
Text(
'Results will appear after you stop typing'
,
style: TextStyle(color: Colors.grey.shade400),
),
],
),
);
}
if
(_results.isEmpty) {
return
Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Icon(Icons.search_off, size:
64
, color: Colors.grey.shade400),
SizedBox(height:
16
),
Text(
'No results found'
,
style: TextStyle(fontSize:
18
, color: Colors.grey.shade600),
),
Text(
'Try a different search term'
,
style: TextStyle(color: Colors.grey.shade400),
),
],
),
);
}
return
ListView.builder(
itemCount: _results.length,
itemBuilder: (context, index) {
final
item = _results[index];
return
Card(
margin: EdgeInsets.symmetric(horizontal:
16
, vertical:
4
),
child: ListTile(
title: Text(item[
'title'
] ??
'No title'
),
subtitle: Text(item[
'body'
] ??
'No body'
),
leading: CircleAvatar(
child: Text((index +
1
).toString()),
),
),
);
},
);
}
}
Step-by-Step Explanation
1.
Choose the search approach
– Decide between local filtering, API search, or both.
2.
Create the search UI
– Add a
TextField
with a search icon and clear button.
3.
Implement the search logic
– For local search, filter the list. For API search, make a network request.
4.
Add debouncing
– Use a
Timer
to delay the search until the user stops typing.
5.
Handle states
– Show loading, error, empty, and results states appropriately.
Search Best Practices
✅ Do's
- Always add a clear button to the search field
- Show loading indicators while searching
- Display search results in a clear, scannable format
- Show a "no results" message with helpful suggestions
- Debounce API searches (300-500ms delay)
- Handle errors gracefully with retry options
- Highlight matching text in results (optional)
❌ Don'ts
- Don't search on every keystroke without debouncing
- Don't show raw JSON or error messages
- Don't forget to handle empty searches
- Don't block the UI while searching
- Don't ignore the search input when it's empty
Common Mistakes
❌ Mistake 1: Not debouncing API searches
Without debouncing, every keystroke triggers an API call, causing performance issues and server load.
✅ Correct: Always debounce API searches
Use a
Timer
with a 300-500ms delay before performing the search.
❌ Mistake 2: Not handling empty search
If the user clears the search field, the app should return to the default state (show all items).
✅ Correct: Handle empty search
When the search query is empty, reset the results to show all items or show a placeholder.
❌ Mistake 3: Not cancelling previous requests
If a search takes a long time and the user types another query, the old request should be cancelled.
✅ Correct: Cancel in-flight requests
Use a
CancelToken
or check if the search term has changed before processing results.
🎯 Key Takeaway
Search is a critical feature for apps with large datasets. Use local filtering for small datasets and API search for large ones. Always debounce API searches to prevent unnecessary requests. Handle all states – loading, error, empty, and results. A well-designed search enhances the user experience significantly.