> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Hits Searcher
> Manages search sessions and requests.
export const SearchRequest = () =>
search request
;
export const SearchQuery = () =>
search query
;
export const Index = () =>
index
;
export const Facet = () =>
facet
;
export const Events = () =>
events
;
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
```dart Signature theme={"system"}
HitsSearcher(
String applicationID,
String apiKey,
String indexName,
// Optional parameters
bool disjunctiveFacetingEnabled,
Duration debounce,
)
HitsSearcher.create(
String applicationID,
String apiKey,
SearchState state,
// Optional parameters
bool disjunctiveFacetingEnabled,
Duration debounce,
)
FacetSearcher(
String applicationID,
String apiKey,
String indexName,
String facet,
// Optional parameters
Duration debounce,
)
FacetSearcher.create(
String applicationID,
String apiKey,
FacetSearchState state,
// Optional parameters
Duration debounce,
)
MultiSearcher(
String applicationID,
String apiKey,
// Optional parameters
EventTracker eventTracker
)
```
Open the live Hits Searcher example in your browser.
## About this widget
The component handling a ,
`HitsSearcher` has the following behavior:
* Distinct state changes (including initial state) will trigger a search operation
* State changes are debounced
* On a new search request, any previous ongoing search calls will be cancelled
Algolia for Flutter comes with these searchers:
* `HitsSearcher`. Searches a single .
* `FacetSearcher`. Searches for values.
* `MultiSearcher`. Aggregates the hits and facet searchers. This is useful for building a federated search, or query suggestions.
## Examples
1. Create a `HitsSearcher`
2. Update search state with [`query`](#param-query) and [`applyState`](/doc/api-reference/widgets/instantsearch/flutter#param-apply-state)
3. Listen to search [`responses`](#param-responses) and build the UI
4. [`dispose`](#param-dispose) of underlying resources
```dart Dart icon=code theme={"system"}
class SearchScreen extends StatefulWidget {
const SearchScreen({super.key});
@override
State createState() => _SearchScreenState();
}
class _SearchScreenState extends State {
// 1. Create a Hits Searcher
final hitsSearcher = HitsSearcher(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
indexName: 'YourIndexName',
);
@override
Widget build(BuildContext context) => Scaffold(
appBar: AppBar(
// 2. Run your search operations
title: TextField(
onChanged: (input) => hitsSearcher.query(input),
decoration: const InputDecoration(
hintText: 'Search...',
prefixIcon: Icon(Icons.search),
fillColor: Colors.white,
filled: true,
),
),
),
// 3.1 Listen to search responses
body: StreamBuilder(
stream: hitsSearcher.responses,
builder: (_, snapshot) {
if (snapshot.hasData) {
final response = snapshot.data;
final hits = response?.hits.toList() ?? [];
// 3.2 Display your search hits
return ListView.builder(
itemCount: hits.length,
itemBuilder: (_, i) => ListTile(title: Text(hits[i]['title'])),
);
} else {
return const Center(child: CircularProgressIndicator());
}
},
),
);
@override
void dispose() {
super.dispose();
// 4. Release underling resources
hitsSearcher.dispose();
}
}
```
## HitsSearcher
The ID of your application.
```dart Dart icon=code theme={"system"}
final hitsSearcher = HitsSearcher(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
indexName: 'YourIndexName',
);
```
Your application's [Search-only API key](/doc/guides/security/api-keys#search-only-api-key).
```dart Dart icon=code theme={"system"}
final hitsSearcher = HitsSearcher(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
indexName: 'YourIndexName',
);
```
The index to search into.
```dart Dart icon=code theme={"system"}
final hitsSearcher = HitsSearcher(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
indexName: 'YourIndexName',
);
```
Initial search state.
```dart Dart icon=code theme={"system"}
final hitsSearcher = HitsSearcher.create(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
state: const SearchState(indexName: 'YourIndexName'),
);
```
Whether disjunctive faceting is enabled.
```dart Dart icon=code theme={"system"}
final hitsSearcher = HitsSearcher(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
indexName: 'YourIndexName',
disjunctiveFacetingEnabled: true,
);
```
Search operation debounce duration.
```dart Dart icon=code theme={"system"}
final hitsSearcher = HitsSearcher(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
indexName: 'YourIndexName',
debounce: const Duration(milliseconds: 100),
);
```
### Fields
Stream of search responses.
```dart Dart icon=code theme={"system"}
StreamBuilder(
stream: hitsSearcher.responses,
builder: (context, snapshot) {
if (snapshot.hasData) {
final response = snapshot.data!;
return Column(
children: [
Text('${response.nbHits} hits found'),
ListView.builder(
itemCount: response.hits.length,
itemBuilder: (context, index) {
final hit = response.hits[index];
return ListTile(title: Text(hit['name']));
},
),
],
);
} else {
return const CircularProgressIndicator();
}
},
);
```
Stream of search states.
```dart Dart icon=code theme={"system"}
StreamBuilder(
stream: searcher.state,
builder: (context, snapshot) {
if (snapshot.hasData) {
final query = snapshot.data?.query ?? '';
return Text('Query: $query');
} else {
return const CircularProgressIndicator();
}
},
);
```
Instance responsible for handling and sending user related to search interactions,
such as clicks, conversions, and views.
These events help to personalize the user's search experience by providing insights into user behavior.
`eventTracker` is automatically integrated with the `HitsSearcher` to track events when users interact with the search results.
```dart Dart icon=code theme={"system"}
hitsSearcher.eventTracker.clickedObjects(
indexName: 'YourIndexName',
objectIDs: ['objectID1', 'objectID2'],
eventName: 'your_event_name',
);
```
### Methods
Triggers a search operation with given .
```dart Dart icon=code theme={"system"}
hitsSearcher.query('book');
```
Applies a search state configuration and triggers a search operation.
```dart Dart icon=code theme={"system"}
hitsSearcher.applyState((state) => state.copyWith(query: 'book', page: 0));
```
Gets the latest `SearchResponse` value submitted by [`responses`](#param-responses) stream:
```dart Dart icon=code theme={"system"}
final response = hitsSearcher.snapshot();
```
Releases all underlying resources
```dart Dart icon=code theme={"system"}
hitsSearcher.dispose();
```
## FacetSearcher
The ID of your application.
```dart Dart icon=code theme={"system"}
final facetSearcher = FacetSearcher(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
indexName: 'YourIndexName',
facet: 'facet_attribute',
);
```
Your application's [Search-only API key](/doc/guides/security/api-keys#search-only-api-key).
```dart Dart icon=code theme={"system"}
final facetSearcher = FacetSearcher(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
indexName: 'YourIndexName',
facet: 'facet_attribute',
);
```
The index to search into.
```dart Dart icon=code theme={"system"}
final facetSearcher = FacetSearcher(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
indexName: 'YourIndexName',
facet: 'facet_attribute',
);
```
The facet name to search into when doing search for facet values.
```dart Dart icon=code theme={"system"}
final facetSearcher = FacetSearcher(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
indexName: 'YourIndexName',
facet: 'facet_attribute',
);
```
Initial facet search state.
```dart Dart icon=code theme={"system"}
final facetSearcher = FacetSearcher.create(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
state: FacetSearchState(
searchState: SearchState(indexName: 'YourIndexName'),
facet: 'facet_attribute',
),
);
```
Search operation debounce duration.
```dart Dart icon=code theme={"system"}
final facetSearcher = FacetSearcher(
applicationID: 'YourApplicationID',
apiKey: 'YourSearchOnlyApiKey',
indexName: 'YourIndexName',
facet: 'facet_attribute',
debounce: const Duration(milliseconds: 100),
);
```
### Fields
Stream of search responses.
```dart Dart icon=code theme={"system"}
StreamBuilder(
stream: facetSearcher.responses,
builder: (BuildContext context,
AsyncSnapshot snapshot) {
if (snapshot.hasData) {
final response = snapshot.data;
final facets = response?.facetHits.toList() ?? [];
return ListView.builder(
itemCount: facets.length,
itemBuilder: (BuildContext context, int index) {
final facet = facets[index];
return ListTile(
title: Text(facet.value)
);
},
);
} else {
return const CircularProgressIndicator();
}
},
)
```
Stream of facet search states
```dart Dart icon=code theme={"system"}
StreamBuilder(
stream: searcher.state,
builder: (context, snapshot) {
if (snapshot.hasData) {
final query = snapshot.data?.facetQuery ?? '';
return Text('Facet query: $query');
} else {
return const CircularProgressIndicator();
}
},
);
```
### Methods
Triggers a search operation with given search query
```dart Dart icon=code theme={"system"}
facetSearcher.query('book');
```
Applies a search state configuration and triggers a search operation
```dart Dart icon=code theme={"system"}
facetSearcher.applyState((state) => state.copyWith(facetQuery: 'book'));
```
Gets the latest `FacetSearchResponse` value submitted by [`responses`](#param-responses-1) stream:
```dart Dart icon=code theme={"system"}
final response = facetSearcher.snapshot();
```
Releases all underlying resources
```dart Dart icon=code theme={"system"}
facetSearcher.dispose();
```
## MultiSearcher
`MultiSearcher` lets you simultaneously search for hits and facet values in different indices of the same Algolia application.
It instantiates and manages `HitsSearcher` and `FacetSearcher` instances. Once created, these searchers behave like their independently instantiated counterparts.
```dart Dart icon=code theme={"system"}
final multiSearcher = MultiSearcher(
applicationID = ApplicationID("YourApplicationID"),
apiKey = APIKey("YourSearchOnlyApiKey"),
eventTracker: Insights('MY_APPLICATION_ID', 'MY_API_KEY'),
)
```
### Methods
Releases all underlying resources
```dart Dart icon=code theme={"system"}
multiSearcher.dispose();
```
Adds a new `HitsSearcher` to the multi-searcher.
```dart Dart icon=code theme={"system"}
final hitsSearcher = multiSearcher.addHitsSearcher(
initialState: const SearchState(
indexName: 'instant_search',
),
);
```
Adds a new `FacetSearcher` to the multi-searcher.
```dart Dart icon=code theme={"system"}
final facetSearcher = multiSearcher.addFacetSearcher(
initialState: const FacetSearchState(
facet: 'brand',
searchState: SearchState(
indexName: 'instant_search',
),
)
);
```