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

Copy 
1

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

Props

placeholder
type: string
default: Search
Optional

The input placeholder.
Copy 
1
2
3

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

The submit button text.
Copy 
1
2
3

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

The clear button text.
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.
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.
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