Search Parameters

Configure Algolia search parameters to control filtering, faceting, and result display

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:

1. Per-index (recommended) - using the indices prop
2. 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:

1. Go to your Algolia dashboard
2. Open the “Search” page
3. Use the search parameters panel to test filters, facets, etc.
4. 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}
    />
  );
}