Hits Searcher - Algolia

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 demo

This component handles search requests and manages search sessions. The HitsSearcher component 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 index.
FacetSearcher. Searches for facet values.
MultiSearcher. Aggregates the hits and facet searchers. This is useful for building a federated search, or query suggestions.

Examples

Create a HitsSearcher
Update search state with query and applyState
Listen to search responses and build the UI
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 events 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 search query.

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',
      ),
    )
);

Algolia for Flutter

​About this widget

​Examples

​HitsSearcher

​Fields

​Methods

​FacetSearcher

​Fields

​Methods

​MultiSearcher

​Methods

About this widget

Examples

HitsSearcher

Fields

Methods

FacetSearcher

Fields

Methods

MultiSearcher

Methods