Search Parameters - DocSearch

DocSearch uses Algolia’s powerful search API. You can configure search parameters to control filtering, ranking, attributes, and more.

Configuring Search Parameters

Search parameters can be set at two levels:

Per-index (recommended) - using the indices prop
Global (deprecated) - using the top-level searchParameters prop

Per-Index Configuration

import { DocSearch } from '@docsearch/react';

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'documentation',
      searchParameters: {
        hitsPerPage: 20,
        facetFilters: ['version:v2', 'language:en'],
        attributesToRetrieve: ['hierarchy', 'content', 'url'],
      }
    }
  ]}
/>

Using per-index searchParameters allows different configuration for each index when searching multiple indices.

Common Search Parameters

Filtering

facetFilters

Filter results by facet values. Supports AND/OR logic:

searchParameters: {
  // AND: must match all
  facetFilters: ['version:v2', 'language:en'],
  
  // OR: match any within nested array
  facetFilters: [
    'version:v2',
    ['language:en', 'language:es']
  ],
}

Common use cases:

Version filtering: facetFilters: ['version:latest']
Language filtering: facetFilters: ['language:en']
Category filtering: facetFilters: ['category:tutorial']

filters

Use filter expressions for more complex logic:

searchParameters: {
  filters: 'published = true AND (category:guide OR category:tutorial)',
}

Operators:

Comparison: =, !=, <, <=, >, >=
Logic: AND, OR, NOT
Grouping: ()

Attributes

attributesToRetrieve

Specify which attributes to retrieve (improves performance):

searchParameters: {
  attributesToRetrieve: [
    'hierarchy.lvl0',
    'hierarchy.lvl1',
    'hierarchy.lvl2',
    'hierarchy.lvl3',
    'content',
    'type',
    'url'
  ],
}

By default, DocSearch retrieves hierarchy.lvl0 through hierarchy.lvl6, content, type, and url. Only override if you need to optimize performance or exclude certain attributes.

attributesToSnippet

Control snippet length for each attribute:

searchParameters: {
  attributesToSnippet: [
    'hierarchy.lvl1:10',  // 10 words
    'hierarchy.lvl2:10',
    'content:15',         // 15 words
  ],
}

restrictSearchableAttributes

Limit which attributes are searched:

searchParameters: {
  // Only search in content, not titles
  restrictSearchableAttributes: ['content'],
  
  // Or search specific hierarchy levels
  restrictSearchableAttributes: ['hierarchy.lvl1', 'hierarchy.lvl2', 'content'],
}

Pagination and Limits

hitsPerPage

Number of results per query:

searchParameters: {
  hitsPerPage: 20, // Default is 20
}

For DocSearch, combine hitsPerPage with the maxResultsPerGroup prop to control result display.

Highlighting and Snippeting

highlightPreTag / highlightPostTag

Customize highlight markup:

searchParameters: {
  highlightPreTag: '<em class="highlight">',
  highlightPostTag: '</em>',
}

Default values:

highlightPreTag: '<mark>'
highlightPostTag: '</mark>'

snippetEllipsisText

Customize ellipsis text:

searchParameters: {
  snippetEllipsisText: '…', // Default
}

Advanced Parameters

distinct

Remove duplicate or similar results:

searchParameters: {
  distinct: true,
  // or specify the number of distinct hits per group
  distinct: 2,
}

clickAnalytics

Enable click analytics:

searchParameters: {
  clickAnalytics: true,
}

When the top-level insights prop is true, clickAnalytics is automatically enabled unless explicitly set to false in searchParameters.

optionalWords

Make certain query words optional:

searchParameters: {
  optionalWords: ['react', 'javascript'],
}

removeWordsIfNoResults

Automatically remove words if no results found:

searchParameters: {
  removeWordsIfNoResults: 'allOptional', // or 'firstWords' or 'lastWords'
}

Complete SearchParamsObject Type

Here’s the TypeScript interface from algoliasearch:

import type { SearchParamsObject } from 'algoliasearch/lite';

interface DocSearchIndex {
  name: string;
  searchParameters?: SearchParamsObject;
}

SearchParamsObject includes:

query?: string
facetFilters?: string[] | string[][]
filters?: string
attributesToRetrieve?: string[]
attributesToSnippet?: string[]
restrictSearchableAttributes?: string[]
hitsPerPage?: number
highlightPreTag?: string
highlightPostTag?: string
snippetEllipsisText?: string
distinct?: boolean | number
clickAnalytics?: boolean
And many more…

Full API Reference

See the Algolia API documentation for all available search parameters.

Common Patterns

Version-Specific Documentation

function VersionedDocSearch({ version }) {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices={[
        {
          name: 'documentation',
          searchParameters: {
            facetFilters: [`version:${version}`, 'language:en'],
            hitsPerPage: 15,
          }
        }
      ]}
    />
  );
}

Multi-Language Search

function MultiLanguageDocSearch({ language }) {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices={[
        {
          name: 'documentation',
          searchParameters: {
            facetFilters: [`language:${language}`],
            // Fallback to English if no results
            removeWordsIfNoResults: 'allOptional',
          }
        }
      ]}
    />
  );
}

Filtered Category Search

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'documentation',
      searchParameters: {
        facetFilters: [[
          'category:getting-started',
          'category:guides',
          'category:tutorials'
        ]],
      }
    }
  ]}
/>

Performance-Optimized Search

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'documentation',
      searchParameters: {
        // Retrieve only essential fields
        attributesToRetrieve: [
          'hierarchy.lvl0',
          'hierarchy.lvl1',
          'hierarchy.lvl2',
          'content',
          'url'
        ],
        // Shorter snippets
        attributesToSnippet: [
          'content:10',
        ],
        // Fewer results
        hitsPerPage: 10,
      }
    }
  ]}
  maxResultsPerGroup={5}
/>

Search with Ask AI Parameters

When using Ask AI, you can also configure search parameters for the AI context:

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'documentation',
      searchParameters: {
        // Regular search parameters
        facetFilters: ['version:v2'],
        hitsPerPage: 20,
      }
    }
  ]}
  askAi={{
    assistantId: 'your-assistant-id',
    searchParameters: {
      // Ask AI specific parameters
      facetFilters: ['version:v2', 'language:en'],
      attributesToRetrieve: ['content', 'hierarchy', 'url'],
      distinct: true,
    }
  }}
/>

Ask AI searchParameters are separate from index searchParameters. They control what content the AI uses to generate answers.

Debugging Search Parameters

Viewing Search Requests

Use transformSearchClient to log search requests:

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'documentation',
      searchParameters: {
        facetFilters: ['version:v2'],
      }
    }
  ]}
  transformSearchClient={(searchClient) => {
    return {
      ...searchClient,
      search(requests) {
        console.log('Search requests:', requests);
        return searchClient.search(requests);
      },
    };
  }}
/>

Testing Parameters

Test parameters in Algolia dashboard before adding them to your code:

Go to your Algolia dashboard
Open the “Search” page
Use the search parameters panel to test filters, facets, etc.
Once satisfied, copy the parameters to your code

Migration from Deprecated Props

The top-level searchParameters prop is deprecated. Use per-index parameters with the indices prop instead.

Before (Deprecated)

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="documentation"
  searchParameters={{
    hitsPerPage: 20,
    facetFilters: ['version:v2'],
  }}
/>

After (Recommended)

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'documentation',
      searchParameters: {
        hitsPerPage: 20,
        facetFilters: ['version:v2'],
      }
    }
  ]}
/>

Complete Example

import { DocSearch } from '@docsearch/react';
import '@docsearch/css';

function App() {
  const currentVersion = 'v2';
  const userLanguage = 'en';
  
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices={[
        {
          name: 'documentation',
          searchParameters: {
            // Filtering
            facetFilters: [
              `version:${currentVersion}`,
              `language:${userLanguage}`
            ],
            filters: 'published = true',
            
            // Attributes
            attributesToRetrieve: [
              'hierarchy.lvl0',
              'hierarchy.lvl1',
              'hierarchy.lvl2',
              'hierarchy.lvl3',
              'content',
              'type',
              'url'
            ],
            attributesToSnippet: [
              'hierarchy.lvl1:10',
              'hierarchy.lvl2:10',
              'content:15'
            ],
            
            // Results
            hitsPerPage: 20,
            distinct: true,
            
            // Highlighting
            highlightPreTag: '<mark class="search-highlight">',
            highlightPostTag: '</mark>',
            snippetEllipsisText: '…',
            
            // Analytics
            clickAnalytics: true,
          }
        },
        {
          name: 'blog_posts',
          searchParameters: {
            facetFilters: [`language:${userLanguage}`],
            hitsPerPage: 5,
            filters: 'published = true',
          }
        }
      ]}
      maxResultsPerGroup={10}
      insights={true}
    />
  );
}

Get Started

Installation

Core Concepts

Guides

Advanced

​Configuring Search Parameters

​Per-Index Configuration

​Common Search Parameters

​Filtering

​facetFilters

​filters

​Attributes

​attributesToRetrieve

​attributesToSnippet

​restrictSearchableAttributes

​Pagination and Limits

​hitsPerPage

​Highlighting and Snippeting

​highlightPreTag / highlightPostTag

​snippetEllipsisText

​Advanced Parameters

​distinct

​clickAnalytics

​optionalWords

​removeWordsIfNoResults

​Complete SearchParamsObject Type

Full API Reference

​Common Patterns

​Version-Specific Documentation

​Multi-Language Search

​Filtered Category Search

​Performance-Optimized Search

​Search with Ask AI Parameters

​Debugging Search Parameters

​Viewing Search Requests

​Testing Parameters

​Migration from Deprecated Props

​Before (Deprecated)

​After (Recommended)

​Complete Example

Build docs developers (and LLMs) love

Configuring Search Parameters

Per-Index Configuration

Common Search Parameters

Filtering

facetFilters

filters

Attributes

attributesToRetrieve

attributesToSnippet

restrictSearchableAttributes

Pagination and Limits

hitsPerPage

Highlighting and Snippeting

highlightPreTag / highlightPostTag

snippetEllipsisText

Advanced Parameters

distinct

clickAnalytics

optionalWords

removeWordsIfNoResults

Complete SearchParamsObject Type

Common Patterns

Version-Specific Documentation

Multi-Language Search

Filtered Category Search

Performance-Optimized Search

Search with Ask AI Parameters

Debugging Search Parameters

Viewing Search Requests

Testing Parameters

Migration from Deprecated Props

Before (Deprecated)

After (Recommended)

Complete Example