Skip to main content

​
What are connectors?

Connectors are the core building blocks of InstantSearch.js widgets. They provide the logic for search widgets without the rendering, allowing you to build custom UI components while leveraging InstantSearch’s powerful search functionality. Each connector:
  • Manages search state and parameters
  • Handles search results processing
  • Provides render and refine functions
  • Works with any UI library or framework

​
How connectors work

Connectors follow a simple pattern: 
const customWidget = connectSearchBox(
  (renderOptions, isFirstRender) => {
    const { query, refine, clear } = renderOptions;
    
    // Your custom rendering logic here
  }
);
The connector calls your render function with:
  • renderOptions: The current state and available actions
  • isFirstRender: Boolean indicating if this is the initial render

​
Available connectors

Search Box

Input widget for the main search query

​
Results

Hits

Display search results

Infinite Hits

Display search results with infinite scrolling

​
Filtering

Refinement List

Multi-select faceted filtering

Hierarchical Menu

Multi-level hierarchical faceted filtering

Menu

Single-select faceted filtering

Range

Filter by numeric range

Rating Menu

Filter by rating values

Numeric Menu

Filter by numeric ranges with predefined options

Toggle Refinement

On/off filtering based on attribute value

​
Current Filters

Current Refinements

Display and remove active filters

Clear Refinements

Button to clear all active filters

Pagination

Navigate between result pages

Breadcrumb

Display hierarchical navigation path

​
UI Controls

Hits Per Page

Select number of results per page

Sort By

Switch between indices or sorting strategies

Stats

Display search statistics

​
Other

Configure

Set search parameters programmatically

Powered By

Display Algolia logo

Geo Search

Search and filter by geographic location

​
Creating custom widgets

To create a custom widget with a connector:
  1. Import the connector
  2. Define your rendering function
  3. Call the connector with your rendering function
  4. Add the widget to your InstantSearch instance
import { connectSearchBox } from 'instantsearch.js/es/connectors';

const customSearchBox = connectSearchBox(
  (renderOptions, isFirstRender) => {
    const { query, refine, widgetParams } = renderOptions;
    const { container } = widgetParams;
    
    container.innerHTML = `
      <input 
        type="search" 
        value="${query}"
        placeholder="Search..."
      />
    `;
    
    container.querySelector('input').addEventListener('input', (e) => {
      refine(e.target.value);
    });
  }
);

search.addWidgets([
  customSearchBox({
    container: document.querySelector('#searchbox'),
  }),
]);

Build docs developers (and LLMs) love

Get started for freeTalk to us