> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/algolia/docsearch/llms.txt
> Use this file to discover all available pages before exploring further.

# VitePress Integration

> Learn how to integrate DocSearch with VitePress documentation sites

DocSearch provides native support for VitePress through the `@docsearch/react` package. This guide shows you how to set up DocSearch in your VitePress documentation site.

## Overview

VitePress has built-in support for Algolia DocSearch through its default theme configuration. You can enable DocSearch by adding configuration to your VitePress config file.

<Note>
  VitePress uses the same DocSearch integration that powers many documentation sites. Make sure you've [applied for DocSearch](https://docsearch.algolia.com/apply) to get your credentials.
</Note>

## Installation

No additional packages are required! VitePress includes DocSearch support out of the box. You just need to configure it.

## Configuration

<Steps>
  <Step title="Get your credentials">
    Before configuring DocSearch, you need:

    * `appId` - Your Algolia application ID
    * `apiKey` - Your search-only API key
    * `indexName` - Your index name

    Get these by [applying to DocSearch](https://docsearch.algolia.com/apply) or from your Algolia dashboard.
  </Step>

  <Step title="Configure VitePress">
    Add the DocSearch configuration to your `.vitepress/config.js` (or `.ts`, `.mjs`) file:

    ```js title=".vitepress/config.js" theme={null}
    export default {
      themeConfig: {
        search: {
          provider: 'algolia',
          options: {
            appId: 'YOUR_APP_ID',
            apiKey: 'YOUR_SEARCH_API_KEY',
            indexName: 'YOUR_INDEX_NAME'
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Test your search">
    Restart your VitePress dev server and press `Ctrl+K` (or `Cmd+K` on Mac) to open the search modal. You should see the DocSearch interface.
  </Step>
</Steps>

## Configuration Options

### Basic Configuration

The minimum required configuration:

```js title=".vitepress/config.js" theme={null}
export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME'
      }
    }
  }
}
```

### Search Parameters

Customize search behavior with Algolia search parameters:

```js title=".vitepress/config.js" theme={null}
export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        searchParameters: {
          facetFilters: ['language:en', 'version:v1']
        }
      }
    }
  }
}
```

### Placeholder Text

Customize the search box placeholder:

```js title=".vitepress/config.js" theme={null}
export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        placeholder: 'Search documentation'
      }
    }
  }
}
```

### Translations

Customize button and modal text:

```js title=".vitepress/config.js" theme={null}
export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        translations: {
          button: {
            buttonText: 'Search',
            buttonAriaLabel: 'Search documentation'
          },
          modal: {
            searchBox: {
              resetButtonTitle: 'Clear query',
              resetButtonAriaLabel: 'Clear query',
              cancelButtonText: 'Cancel',
              cancelButtonAriaLabel: 'Cancel'
            },
            startScreen: {
              recentSearchesTitle: 'Recent',
              noRecentSearchesText: 'No recent searches',
              saveRecentSearchButtonTitle: 'Save to recent searches',
              removeRecentSearchButtonTitle: 'Remove from recent searches',
              favoriteSearchesTitle: 'Favorites',
              removeFavoriteSearchButtonTitle: 'Remove from favorites'
            },
            errorScreen: {
              titleText: 'Unable to fetch results',
              helpText: 'Check your network connection'
            },
            footer: {
              selectText: 'to select',
              navigateText: 'to navigate',
              closeText: 'to close',
              searchByText: 'Search by'
            },
            noResultsScreen: {
              noResultsText: 'No results for',
              suggestedQueryText: 'Try searching for',
              reportMissingResultsText: 'Missing results?',
              reportMissingResultsLinkText: 'Let us know'
            }
          }
        }
      }
    }
  }
}
```

## Multi-Language Sites

For multi-language VitePress sites, configure search per locale:

```js title=".vitepress/config.js" theme={null}
export default {
  locales: {
    root: {
      label: 'English',
      lang: 'en',
      themeConfig: {
        search: {
          provider: 'algolia',
          options: {
            appId: 'YOUR_APP_ID',
            apiKey: 'YOUR_SEARCH_API_KEY',
            indexName: 'YOUR_INDEX_NAME',
            searchParameters: {
              facetFilters: ['language:en']
            },
            placeholder: 'Search documentation'
          }
        }
      }
    },
    fr: {
      label: 'Français',
      lang: 'fr',
      themeConfig: {
        search: {
          provider: 'algolia',
          options: {
            appId: 'YOUR_APP_ID',
            apiKey: 'YOUR_SEARCH_API_KEY',
            indexName: 'YOUR_INDEX_NAME',
            searchParameters: {
              facetFilters: ['language:fr']
            },
            placeholder: 'Rechercher dans la documentation'
          }
        }
      }
    }
  }
}
```

## Custom Component Integration

If you need more control, you can directly use the `@docsearch/react` package in your custom VitePress theme.

<Steps>
  <Step title="Install DocSearch React">
    ```bash npm theme={null}
    npm install @docsearch/react
    ```
  </Step>

  <Step title="Create a custom component">
    Create a Vue component that wraps DocSearch:

    ```vue title=".vitepress/theme/components/DocSearch.vue" theme={null}
    <script setup>
    import { onMounted } from 'vue'
    import docsearch from '@docsearch/js'
    import '@docsearch/css'

    onMounted(() => {
      docsearch({
        container: '#docsearch',
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME'
      })
    })
    </script>

    <template>
      <div id="docsearch"></div>
    </template>
    ```
  </Step>

  <Step title="Use the component">
    Import and use your custom component in your VitePress theme:

    ```js title=".vitepress/theme/index.js" theme={null}
    import DefaultTheme from 'vitepress/theme'
    import DocSearch from './components/DocSearch.vue'
    import './custom.css'

    export default {
      extends: DefaultTheme,
      enhanceApp({ app }) {
        app.component('DocSearch', DocSearch)
      }
    }
    ```
  </Step>
</Steps>

## Ask AI Integration

<Note>
  Ask AI is available in DocSearch v4+. VitePress's built-in integration may not support all Ask AI features. For full Ask AI support, use the custom component approach.
</Note>

To enable Ask AI with a custom integration:

```vue title=".vitepress/theme/components/DocSearch.vue" theme={null}
<script setup>
import { onMounted } from 'vue'
import docsearch from '@docsearch/js'
import '@docsearch/css'

onMounted(() => {
  docsearch({
    container: '#docsearch',
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    askAi: 'YOUR_ASSISTANT_ID'
  })
})
</script>

<template>
  <div id="docsearch"></div>
</template>
```

## Crawler Configuration

VitePress sites require specific crawler configuration. Create a `docsearch.config.json`:

```json title="docsearch.config.json" theme={null}
{
  "index_name": "YOUR_INDEX_NAME",
  "start_urls": ["https://yourdocs.com/"],
  "selectors": {
    "lvl0": {
      "selector": ".sidebar .active",
      "attribute": "textContent"
    },
    "lvl1": ".content h1",
    "lvl2": ".content h2",
    "lvl3": ".content h3",
    "lvl4": ".content h4",
    "lvl5": ".content h5",
    "text": ".content p, .content li"
  }
}
```

<Note>
  Adjust selectors based on your custom VitePress theme. The default theme uses `.content` for main content.
</Note>

## Complete Example

Here's a complete VitePress configuration with DocSearch:

```js title=".vitepress/config.js" theme={null}
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Documentation',
  description: 'My awesome documentation site',
  
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: 'Introduction',
          items: [
            { text: 'Getting Started', link: '/guide/getting-started' },
            { text: 'Installation', link: '/guide/installation' }
          ]
        }
      ]
    },
    
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        placeholder: 'Search docs',
        searchParameters: {
          facetFilters: ['language:en']
        }
      }
    },
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/yourusername/yourrepo' }
    ]
  }
})
```

## Troubleshooting

### Search not working

1. **Check credentials**: Verify your `appId`, `apiKey`, and `indexName` are correct
2. **Index status**: Ensure your index has been crawled and contains data
3. **Network**: Check browser console for network errors

### No results showing

1. **Crawler setup**: Verify your crawler configuration matches your VitePress structure
2. **Facet filters**: Check if `searchParameters.facetFilters` are too restrictive
3. **Index content**: Visit Algolia dashboard to inspect indexed records

### Styling issues

1. **CSS conflicts**: VitePress styles may conflict with DocSearch. Add custom CSS:

```css title=".vitepress/theme/custom.css" theme={null}
.DocSearch-Button {
  /* Override button styles */
}

.DocSearch-Modal {
  /* Override modal styles */
}
```

2. **Import order**: Ensure DocSearch CSS is imported after VitePress theme CSS

## Next Steps

<CardGroup cols={2}>
  <Card title="Styling DocSearch" icon="palette" href="/concepts/styling">
    Customize the appearance to match your VitePress theme
  </Card>

  <Card title="API Reference" icon="code" href="/api/configuration">
    Explore all configuration options
  </Card>

  <Card title="Crawler Setup" icon="spider" href="/crawler/configuration">
    Configure the DocSearch crawler for VitePress
  </Card>

  <Card title="Custom Integration" icon="wrench" href="/integrations/custom-integration">
    Build a custom integration with full control
  </Card>
</CardGroup>