Guides / Building Search UI

Upgrade Guides

You are reading the documentation for Angular InstantSearch v3, which is in beta. You can find the v2 documentation here.

Migration from v2 to v3

InstantSearch.js is now a peer dependency

with npm:

$
npm install --save instantsearch@^3

with yarn:

$
yarn add instantsearch@^3

RefinementList: “Show more” button controlled by showMore property

The display of the “Show more” button is no longer inferred by the showMoreLimit and the internal state property canToggleShowMore. It is now controlled by a new input property: showMore: boolean = false.

If you want to use the “Show more” button on the ais-refinement-list, make sure to set the showMore property to true

1
2
3
4
5
<ais-refinement-list
  ...
  [showMore]="true"
>
</ais-refinement-list>

NumericSelector widget has been removed

Use instead ais-numeric-menu.

InfiniteHits: “Show More” button CSS class was renamed

The “Show more” button CSS class has been renamed from showMore to ` loadMore`.

InstantSearch: appId, apiKey and createAlgoliaClient have been removed

This enforces the usage of the searchClient option. createAlgoliaClient has been removed as there is no longer a use case for it.

If you have (something like) the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@Component({
  template: `
    <ais-instantsearch [config]="config">
      <!-- more widgets -->
    </ais-instantsearch>
  `
})
export class AppComponent {
  config = {
    appId: 'YourApplicationID',
    apiKey: 'YourSearchOnlyAPIKey',
    /* ... */
  };
}

Replace it with:

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">
      <!-- more widgets -->
    </ais-instantsearch>
  `
})
export class AppComponent {
  config = {
    searchClient: algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey'),
    /* ... */
  };
}

SortBy items property changed

The name key in items has been renamed to value.

Replace this:

1
2
3
4
5
6
7
<ais-sort-by
  [items]="[
    { name: 'products', label: 'Most relevant' },
    { name: 'products_price_desc', label: 'Highest price' }
  ]"
>
</ais-sort-by>

With this:

1
2
3
4
5
6
7
<ais-sort-by
  [items]="[
    { value: 'instant_search', label: 'Featured' },
    { value: 'instant_search_price_asc', label: 'Price asc.' },
    { value: 'instant_search_price_desc', label: 'Price desc.' },
  ]"
></ais-sort-by>

Migration from v0 to v1

Angular 2 and 4 support drop

In order to support Angular CLI 6 we had to drop the support for older versions, the only supported versions are now: 5, 6 and 7. You can update your Angular 4 application pretty easily by following this guide: https://update.angular.io/.

If you are using Angular +6 you will need an extra step, polyfill process.env by adding in your src/polyfill.ts:

1
(window as any).process = {env: {}};

Widget prefix

The ng- prefix is considered reserved for core implementations into Angular so we dropped it. All the widgets are now only starting with ais-:

1
2
3
4
5
6
7
8
9
10
11
<ais-instantsearch [config]="{...}">
  <ais-hits>
    <ng-template let-hits="hits">
      <div *ngFor="let hit of hits">
        Hit {{hit.objectID}}:
        <ais-highlight attribute="name" [hit]="hit">
        </ais-highlight>
      </div>
    </ng-template>
  </ais-hits>
</ais-instantsearch>

Server-side rendering

  • The createSSRAlgoliaClient util has been renamed to createSSRSearchClient
  • You cannot use the new routing: true option on <ais-instantsearch> widget until resolution of preboot#82

Did you find this page helpful?