API Reference / Angular InstantSearch / ais-instantsearch

ais-instantsearch

Signature 
<ais-instantsearch
  [config]="{
    indexName: string
    searchClient: object
    // Optional parameters
    numberLocale: string
    searchFunction: function
    initialUiState: object
    onStateChange: function
    stalledSearchDelay: number
    routing: boolean|object
    insightsClient: function
  }"
></ais-instantsearch>
Import
Copy 
1
2
3
4
5
6
7
8

import { NgAisInstantSearchModule } from 'angular-instantsearch';

@NgModule({
  imports: [
    NgAisInstantSearchModule.forRoot(),
  ],
})
export class AppModule {}

1. Follow additional steps in Optimize build size to ensure your code is correctly bundled.
2. This imports all the widgets, even the ones you don’t use. Read the Getting started guide for more information.

See code examples

About this widget

The ais-instantsearch widget is a wrapper that lets you configure the credentials for search. This component automatically provides the search state to all its children.

Note that every other Angular InstantSearch widgets must be wrapped under this one.

Examples

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

import algoliasearch from 'algoliasearch/lite';

@Component({
  template: `
    <ais-instantsearch [config]="config">
      <!-- Widgets -->
    </ais-instantsearch>
  `,
})
export class AppComponent {
  config = {
    indexName: 'instant_search',
    searchClient: algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey'),
  }
}

Props

indexName
type: string
Required

The main index to search into.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

@Component({
  template: `
    <ais-instantsearch [config]="config">
      <!-- Widgets -->
    </ais-instantsearch>
  `,
})
export class AppComponent {
  config = {
    // ...
    indexName: 'instant_search',
  }
}
searchClient
type: object
Required

Provides a search client to ais-instantsearch. To implement a custom search client, take a look at a the custom back-end guide.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import algoliasearch from 'algoliasearch/lite';

@Component({
  template: `
    <ais-instantsearch [config]="config">
      <!-- Widgets -->
    </ais-instantsearch>
  `,
})
export class AppComponent {
  config = {
    // ...
    searchClient: algoliasearch(
      'YourApplicationID',
      'YourSearchOnlyAPIKey'
    ),
  }
}
numberLocale
type: string
Optional

The locale used to display numbers. This is passed to .toLocaleString().
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

@Component({
  template: `
    <ais-instantsearch [config]="config">
      <!-- Widgets -->
    </ais-instantsearch>
  `,
})
export class AppComponent {
  config = {
    // ...
    numberLocale: 'fr',
  }
}
searchFunction
type: function
Optional

A hook that is called each time a search needs to be done, with the helper as a parameter. It’s your responsibility to call helper.search(). This option allows you, for example, to avoid doing searches at page load.

When modifying the state of the helper within search-function, the helper automatically reset the page to 0. If you want to keep the current page, you need to store the information about the page, modify the state and reapply the pagination.

When this option is set, search.helper will no longer emit events, as it’s considered “controlled”. Instead you can either use onStateChange or widgets to handle that behavior.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

@Component({
  template: `
    <ais-instantsearch [config]="config">
      <!-- Widgets -->
    </ais-instantsearch>
  `,
})
export class AppComponent {
  config = {
    // ...
    searchFunction(helper) {
      helper.search();
    }
  }
}
initialUiState
type: object
Optional

Adds a uiState to your instantsearch instance, which provides an initial state to your widgets. To apply the uiState to the search parameters, you must add your widgets to your instantsearch instance. snippets: function: |

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

  @Component({
    template: `
      <ais-instantsearch [config]="config">
        <!-- Widgets -->
      </ais-instantsearch>
    `,
  })
  export class AppComponent {
    config = {
      // ...
      initialUiState: {
        indexName: {
          query: 'phone',
          page: 5,
        },
      },
    }
  }
onStateChange
type: function
Optional

Triggers when the state changes.

Whenever you start using this option, the instance becomes controlled. This means that you become responsible for updating the UI state with setUiState.

This can be useful to perform custom logic whenever the state changes.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

@Component({
  template: `
    <ais-instantsearch [config]="config">
      <!-- Widgets -->
    </ais-instantsearch>
  `,
})
export class AppComponent {
  config = {
    // ...
    onStateChange({ uiState, setUiState }) {
      // Custom logic

      setUiState(uiState);
    },
  }
}
stalledSearchDelay
type: number
default: 200
Optional

Defines a time period after which a search is considered stalled. You can find more information in the slow network guide.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

@Component({
  template: `
    <ais-instantsearch [config]="config">
      <!-- Widgets -->
    </ais-instantsearch>
  `,
})
export class AppComponent {
  config = {
    // ...
    stalledSearchDelay: 500,
  }
}
routing
type: boolean|object
default: false
Optional

The router configuration used to save the UI state into the URL, or any client-side persistence. You can find more information in the routing guide. The object form accepts two attributes:

  • router: object: this object saves the UI state. By default, it uses an instance of the history with the default parameters. It accepts:
    • onUpdate: function: adds an event listener that makes InstantSearch aware of external changes to the storage medium (e.g. the URL). Typically you’ll set up a listener for popstate, which triggers a callback with the current routeState.
    • read: function: reads the routing storage and gets routeState. It doesn’t take any parameters, and returns an object.
    • write: function: pushes routeState into a routing storage.
    • createURL: function: transforms routeState into a URL. It receives an object and returns a string (which may be empty).
    • dispose: function: cleans up all event listeners.
  • stateMapping: object: transforms the uiState into an object that can be saved by the router. The default value is provided by simple. It accepts:
    • stateToRoute: function: transforms a uiState representation into routeState. It receives an object that contains the UI state of all the widgets in the page. It can return any object that is readable by routeToState.
    • routeToState: function: transforms routeState into a uiState representation. It receives an object that contains the UI state stored by the router. It can return any object that is readable by stateToRoute.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

@Component({
  template: `
    <ais-instantsearch [config]="config">
      <!-- Widgets -->
    </ais-instantsearch>
  `,
})
export class AppComponent {
  config = {
    // ...
    routing: true,
  }
}
insightsClient
type: function
Optional

The function exposed by the search-insights (usually window.aa). You need this if you want to send click and conversion events with InstantSearch.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

@Component({
  template: `
    <ais-instantsearch [config]="config">
      <!-- Widgets -->
    </ais-instantsearch>
  `,
})
export class AppComponent {
  config = {
    // ...
    insightsClient: (window as any).aa,
  }
}

HTML output

Copy 
1
2
3

<div class="ais-InstantSearch">
  <!-- Widgets -->
</div>
Did you find this page helpful?
Angular InstantSearch v4