API Reference / Angular InstantSearch Widgets / ais-search-box
Apr. 24, 2019

ais-search-box

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

Widget signature 
<ais-search-box
  // Optional parameters
  placeholder="string"
  submitTitle="string"
  resetTitle="string"
  [searchAsYouType]="boolean"
  [autofocus]="boolean"
></ais-search-box>
See code examples

About this widget #

The ais-search-box widget is used to let the user set a text-based query.

This usually is the main entry point to start search in an InstantSearch context. Most of the time, it is placed at the top of a search experience, so that the user can start searching right away.

Examples #

Edit
Copy 
1

<ais-search-box></ais-search-box>

Props #

placeholder #
type: string
default: Search
Optional

The input placeholder.
Edit
Copy 
1
2
3

<ais-search-box
  placeholder="Search for products..."
></ais-search-box>
submitTitle #
type: string
default: Submit
Optional

The submit button text.
Edit
Copy 
1
2
3

<ais-search-box
  submitTitle="Go"
></ais-search-box>
resetTitle #
type: string
default: Reset
Optional

The clear button text.
Edit
Copy 
1
2
3

<ais-search-box
  resetTitle="Clear"
></ais-search-box>
searchAsYouType #
type: boolean
default: true
Optional

Whether a search needs to be made on every change to the query. If false, new searches are only triggered by clicking the search button or by pressing the Enter key while the search box is focused.
Edit
Copy 
1
2
3

<ais-search-box
  [searchAsYouType]="false"
></ais-search-box>
autofocus #
type: boolean
default: false
Optional

Whether to automatically focus on the input when rendered.
Edit
Copy 
1
2
3

<ais-search-box
  [autofocus]="true"
></ais-search-box>

Customize the UI - connectSearchBox#

If you want to create your own UI of the ais-search-box widget, you can combine the connectSearchBox connector with the BaseWidget class.

See code examples

1. Extend the BaseWidget class#

First of all, you will need to write some boilerplate code in order to initialize correctly the BaseWidget class. This happens in the constructor() of your class extending the BaseWidget class.

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

import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';

@Component({
  selector: 'app-search-box',
  template: '<p>It works!</p>'
})
export class SearchBox extends BaseWidget {
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('SearchBox');
  }
}

There are a couple of things happening in this boilerplate:

  • we create a SearchBox class extending BaseWidget
  • we reference the <ais-instantsearch> parent component instance on the SearchBox widget class
  • we set app-search-box as a selector, so we can use our component as <app-search-box></app-search-box>

2. Connect your custom widget#

The BaseWidget class has a method called createWidget() which takes two arguments: the connector to use and an object of options (instance options) for this connector. We call this method at ngOnInit. This component now implements OnInit.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectSearchBox } from 'instantsearch.js/es/connectors';

@Component({
  selector: 'app-search-box',
  template: '<p>It works!</p>'
})
export class SearchBox extends BaseWidget {
  public state: {
    // render options
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('SearchBox');
  }
  ngOnInit() {
    this.createWidget(connectSearchBox, {
      // instance options
    });
    super.ngOnInit();
  }
}

3. Render from the state#

Your component instance has access to a this.state property which holds the rendering options of the widget.

public state: {
  query: string;
  refine: Function;
  clear: Function;
  isSearchStalled: boolean;
  widgetParams: object;
}
Copy
1
2
3
4
5
6

<input
  type="text"
  #input
  (keyup)="this.state.refine(input.value)"
  [value]="this.state.query"
/>

Rendering options #

query #
type: string

The query from the current search.
refine #
type: function

Sets a new query and triggers a new search.
clear #
type: function

Removes the query and triggers a new search.
isSearchStalled #
type: boolean

Returns true if the search results take more than a certain time to come back from Algolia servers. This can be configured on the instantsearch constructor with the stalledSearchDelay attribute.
widgetParams #
type: object

All original widget options forwarded to the render function.

Instance options #

queryHook #
type: function
Optional

A function that is called just before the search is triggered. It takes two arguments:

  • query: string: the current query string
  • search: function: triggers the search

If the search method is not called, no search is made to Algolia and the UI doesn’t refresh. If the search method is called, the widget is rendered.

This can be useful if you need to:

  • Debounce the number of searches done from the searchBox. You can find more information in the guide on slow network.
  • Programmatically alter the query.

Full example#

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectSearchBox } from 'instantsearch.js/es/connectors';

@Component({
  selector: 'app-search-box',
  template: `
<input
  type="text"
  #input
  (keyup)="this.state.refine(input.value)"
  [value]="this.state.query"
/>
`
})
export class SearchBox extends BaseWidget {
  public state: {
     query: string;
     refine: Function;
     clear: Function;
     isSearchStalled: boolean;
     widgetParams: object;
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('SearchBox');
  }
  ngOnInit() {
    this.createWidget(connectSearchBox, {
      // instance options
    });
    super.ngOnInit();
  }
}

HTML output#

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

<div class="ais-SearchBox">
  <form class="ais-SearchBox-form" novalidate>
    <input class="ais-SearchBox-input" autocomplete="off" autocorrect="off" autocapitalize="off" placeholder="Search for products" spellcheck="false" maxlength="512" type="search" value="" />
    <button class="ais-SearchBox-submit" type="submit" title="Submit the search query.">
      <svg class="ais-SearchBox-submitIcon" xmlns="http://www.w3.org/2000/svg" width="10" height="10" viewBox="0 0 40 40">
        ...
      </svg>
    </button>
    <button class="ais-SearchBox-reset" type="reset" title="Clear the search query." hidden>
      <svg class="ais-SearchBox-resetIcon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" width="10" height="10">
        ...
      </svg>
    </button>
    <span class="ais-SearchBox-loadingIndicator" hidden>
      <svg width="16" height="16" viewBox="0 0 38 38" xmlns="http://www.w3.org/2000/svg" stroke="#444" class="ais-SearchBox-loadingIcon">
        ...
      </svg>
    </span>
  </form>
</div>

Did you find this page helpful?

Angular InstantSearch v3