Hits Searcher

Manages search sessions and requests.

Signature

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
)

View live demo

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 and applyState
3. Listen to search responses and build the UI
4. dispose of underlying resources

Dart

class SearchScreen extends StatefulWidget {
  const SearchScreen({super.key});

  @override
  State<SearchScreen> createState() => _SearchScreenState();
}

class _SearchScreenState extends State<SearchScreen> {
  // 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<SearchResponse>(
          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

applicationID · String · required

The ID of your application.

Dart

final hitsSearcher = HitsSearcher(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  indexName: 'YourIndexName',
);

apiKey · String · required

Your application’s Search-only API key.

Dart

final hitsSearcher = HitsSearcher(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  indexName: 'YourIndexName',
);

indexName · String · required

The index to search into.

Dart

final hitsSearcher = HitsSearcher(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  indexName: 'YourIndexName',
);

state · SearchState · required

Initial search state.

Dart

final hitsSearcher = HitsSearcher.create(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  state: const SearchState(indexName: 'YourIndexName'),
);

disjunctiveFacetingEnabled · bool · default: true

Whether disjunctive faceting is enabled.

Dart

final hitsSearcher = HitsSearcher(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  indexName: 'YourIndexName',
  disjunctiveFacetingEnabled: true,
);

debounce · Duration · default: Duration(milliseconds: 100)

Search operation debounce duration.

Dart

final hitsSearcher = HitsSearcher(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  indexName: 'YourIndexName',
  debounce: const Duration(milliseconds: 100),
);

Fields

responses · Stream<SearchResponse>

Stream of search responses.

Dart

StreamBuilder<SearchResponse>(
  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();
    }
  },
);

state · Stream<SearchState>

Stream of search states.

Dart

StreamBuilder<SearchState>(
  stream: searcher.state,
  builder: (context, snapshot) {
    if (snapshot.hasData) {
      final query = snapshot.data?.query ?? '';
      return Text('Query: $query');
    } else {
      return const CircularProgressIndicator();
    }
  },
);

eventTracker · HitsEventTracker

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

hitsSearcher.eventTracker.clickedObjects(
  indexName: 'YourIndexName',
  objectIDs: ['objectID1', 'objectID2'],
  eventName: 'your_event_name',
);

Methods

query

Triggers a search operation with given .

Dart

hitsSearcher.query('book');

applyState

Applies a search state configuration and triggers a search operation.

Dart

hitsSearcher.applyState((state) => state.copyWith(query: 'book', page: 0));

snapshot

Gets the latest SearchResponse value submitted by responses stream:

Dart

final response = hitsSearcher.snapshot();

dispose

Releases all underlying resources

Dart

hitsSearcher.dispose();

FacetSearcher

applicationID · String · required

The ID of your application.

Dart

final facetSearcher = FacetSearcher(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  indexName: 'YourIndexName',
  facet: 'facet_attribute',
);

apiKey · String · required

Your application’s Search-only API key.

Dart

 final facetSearcher = FacetSearcher(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  indexName: 'YourIndexName',
  facet: 'facet_attribute',
);

indexName · String · required

The index to search into.

Dart

final facetSearcher = FacetSearcher(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  indexName: 'YourIndexName',
  facet: 'facet_attribute',
);

facet · String · required

The facet name to search into when doing search for facet values.

Dart

final facetSearcher = FacetSearcher(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  indexName: 'YourIndexName',
  facet: 'facet_attribute',
);

state · FacetSearchState · required

Initial facet search state.

Dart

final facetSearcher = FacetSearcher.create(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  state: FacetSearchState(
    searchState: SearchState(indexName: 'YourIndexName'),
    facet: 'facet_attribute',
  ),
);

debounce · Duration · default: Duration(milliseconds: 100)

Search operation debounce duration.

Dart

final facetSearcher = FacetSearcher(
  applicationID: 'YourApplicationID',
  apiKey: 'YourSearchOnlyApiKey',
  indexName: 'YourIndexName',
  facet: 'facet_attribute',
  debounce: const Duration(milliseconds: 100),
);

Fields

responses · Stream<FacetSearchResponse>

Stream of search responses.

Dart

StreamBuilder<FacetSearchResponse>(
  stream: facetSearcher.responses,
  builder: (BuildContext context,
      AsyncSnapshot<FacetSearchResponse> 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();
    }
  },
)

state · Stream<FacetSearchState>

Stream of facet search states

Dart

StreamBuilder<FacetSearchState>(
  stream: searcher.state,
  builder: (context, snapshot) {
    if (snapshot.hasData) {
      final query = snapshot.data?.facetQuery ?? '';
      return Text('Facet query: $query');
    } else {
      return const CircularProgressIndicator();
    }
  },
);

Methods

query

Triggers a search operation with given search query

Dart

facetSearcher.query('book');

applyState

Applies a search state configuration and triggers a search operation

Dart

facetSearcher.applyState((state) => state.copyWith(facetQuery: 'book'));

snapshot

Gets the latest FacetSearchResponse value submitted by responses stream:

Dart

final response = facetSearcher.snapshot();

dispose

Releases all underlying resources

Dart

facetSearcher.dispose();

MultiSearcher

strategy · MultipleQueriesStrategy · default: None

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

final multiSearcher = MultiSearcher(
    applicationID = ApplicationID("YourApplicationID"),
    apiKey = APIKey("YourSearchOnlyApiKey"),
    eventTracker: Insights('MY_APPLICATION_ID', 'MY_API_KEY'),
)

Methods

dispose

Releases all underlying resources

Dart

multiSearcher.dispose();

addHitsSearcher

Adds a new HitsSearcher to the multi-searcher.

Dart

final hitsSearcher = multiSearcher.addHitsSearcher(
  initialState: const SearchState(
    indexName: 'instant_search',
  ),
);

addFacetSearcher

Adds a new FacetSearcher to the multi-searcher.

Dart

final facetSearcher = multiSearcher.addFacetSearcher(
    initialState: const FacetSearchState(
      facet: 'brand',
      searchState: SearchState(
        indexName: 'instant_search',
      ),
    )
);