> ## 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.

# DocSearchSidepanel

> Sidepanel component with AI chat interface

The `DocSearchSidepanel` component provides an AI-powered chat interface in a sidepanel that can be integrated into your documentation site. It offers a more conversational way to interact with your documentation using Algolia's Ask AI feature.

## Import

```jsx theme={null}
import { DocSearchSidepanel } from '@docsearch/react';
```

## Usage

<CodeGroup>
  ```jsx Basic Usage theme={null}
  import { DocSearchSidepanel } from '@docsearch/react';

  function App() {
    return (
      <DocSearchSidepanel
        assistantId="YOUR_ASSISTANT_ID"
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indexName="YOUR_INDEX_NAME"
      />
    );
  }
  ```

  ```jsx With Custom Button theme={null}
  import { DocSearchSidepanel } from '@docsearch/react';

  function App() {
    return (
      <DocSearchSidepanel
        assistantId="YOUR_ASSISTANT_ID"
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indexName="YOUR_INDEX_NAME"
        button={{
          variant: 'inline',
          translations: {
            buttonText: 'Chat with AI',
            buttonAriaLabel: 'Open AI chat assistant'
          }
        }}
      />
    );
  }
  ```

  ```jsx Inline Variant theme={null}
  import { DocSearchSidepanel } from '@docsearch/react';

  function App() {
    return (
      <DocSearchSidepanel
        assistantId="YOUR_ASSISTANT_ID"
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indexName="YOUR_INDEX_NAME"
        panel={{
          variant: 'inline',
          side: 'right',
          width: 400,
          expandedWidth: 600
        }}
      />
    );
  }
  ```

  ```jsx With Suggested Questions theme={null}
  import { DocSearchSidepanel } from '@docsearch/react';

  function App() {
    return (
      <DocSearchSidepanel
        assistantId="YOUR_ASSISTANT_ID"
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indexName="YOUR_INDEX_NAME"
        panel={{
          suggestedQuestions: true
        }}
      />
    );
  }
  ```
</CodeGroup>

## Props

### Required Props

<ParamField path="assistantId" type="string" required>
  The assistant ID to use for the Ask AI feature.
</ParamField>

<ParamField path="apiKey" type="string" required>
  Public API key with search permissions for the index.
</ParamField>

<ParamField path="appId" type="string" required>
  Algolia application ID used by the search client.
</ParamField>

<ParamField path="indexName" type="string" required>
  The index name to use for the Ask AI feature. Your assistant will search this index for relevant documents.
</ParamField>

### Configuration

<ParamField path="keyboardShortcuts" type="SidepanelShortcuts" default="{ 'Ctrl/Cmd+I': true }">
  Configuration for keyboard shortcuts. Allows enabling/disabling specific shortcuts.

  Object with optional properties:

  * `'Ctrl/Cmd+I'` (boolean): Enable/disable Ctrl/Cmd+I shortcut to toggle sidepanel
</ParamField>

<ParamField path="theme" type="'light' | 'dark'" default="'light'">
  Theme overrides applied to the Sidepanel button and panel.
</ParamField>

<ParamField path="searchParameters" type="AskAiSearchParameters | AgentStudioSearchParameters">
  Search parameters for AI context retrieval.

  When `agentStudio` is false or not set:

  * `facetFilters` (string\[]): Facet filters to apply
  * `filters` (string): Filter string
  * `attributesToRetrieve` (string\[]): Attributes to retrieve
  * `restrictSearchableAttributes` (string\[]): Restrict searchable attributes
  * `distinct` (boolean | number | string): Distinct parameter

  When `agentStudio` is true, the object is keyed by index name.
</ParamField>

<ParamField path="agentStudio" type="boolean" default="false">
  **Experimental:** Whether to use Agent Studio as the chat backend.

  This is an experimental feature and its API may change without notice in future releases. Use with caution in production environments.
</ParamField>

### Button Configuration

<ParamField path="button" type="SidepanelButtonProps">
  Props specific to the Sidepanel button.

  Object with optional properties:

  * `variant` ('floating' | 'inline', default: 'floating'): Button positioning and styling
  * `translations` (SidepanelButtonTranslations): Button text translations

  Note: `keyboardShortcuts` prop is inherited from the root component.
</ParamField>

### Panel Configuration

<ParamField path="panel" type="SidepanelProps">
  Props specific to the Sidepanel panel.

  Object with optional properties:

  * `variant` ('inline' | 'floating', default: 'floating'): Panel positioning
  * `side` ('left' | 'right', default: 'right'): Side of the page the panel originates from
  * `pushSelector` (string, default: '#root, main, .app, body'): CSS selector for elements to push when using inline variant
  * `width` (number | string, default: '360px'): Panel width
  * `expandedWidth` (number | string, default: '580px'): Panel width when expanded
  * `portalContainer` (DocumentFragment | Element): Container element for portal
  * `suggestedQuestions` (boolean, default: false): Enable suggested questions display
  * `translations` (SidepanelTranslations): Panel-specific translations
</ParamField>

### Callbacks

<ParamField path="onReady" type="() => void">
  Callback fired when the component is ready.
</ParamField>

<ParamField path="onOpen" type="() => void">
  Callback fired when the modal or sidepanel opens.
</ParamField>

<ParamField path="onClose" type="() => void">
  Callback fired when the modal or sidepanel closes.
</ParamField>

<ParamField path="onSidepanelOpen" type="() => void">
  Callback fired specifically when the sidepanel opens.
</ParamField>

<ParamField path="onSidepanelClose" type="() => void">
  Callback fired specifically when the sidepanel closes.
</ParamField>

## Button Variants

### Floating Button (default)

The floating variant displays a button in the bottom-right corner of the screen with just the AI icon:

```jsx theme={null}
<DocSearchSidepanel
  assistantId="YOUR_ASSISTANT_ID"
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX"
  button={{ variant: 'floating' }}
/>
```

### Inline Button

The inline variant displays the button inline where it's rendered with text:

```jsx theme={null}
<DocSearchSidepanel
  assistantId="YOUR_ASSISTANT_ID"
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX"
  button={{
    variant: 'inline',
    translations: { buttonText: 'Ask AI' }
  }}
/>
```

## Panel Variants

### Floating Panel (default)

The floating variant is positioned above all other content on the page:

```jsx theme={null}
<DocSearchSidepanel
  assistantId="YOUR_ASSISTANT_ID"
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX"
  panel={{ variant: 'floating' }}
/>
```

### Inline Panel

The inline variant pushes page content when opened:

```jsx theme={null}
<DocSearchSidepanel
  assistantId="YOUR_ASSISTANT_ID"
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX"
  panel={{
    variant: 'inline',
    pushSelector: '#main-content'
  }}
/>
```

## Ref Methods

When using `React.forwardRef`, the component exposes a `DocSearchRef` object:

<ResponseField name="openModal" type="function">
  Opens the search modal (if integrated with DocSearch).
</ResponseField>

<ResponseField name="closeModal" type="function">
  Closes the search modal (if integrated with DocSearch).
</ResponseField>

<ResponseField name="openSidepanel" type="function">
  Opens the sidepanel programmatically.
</ResponseField>

<ResponseField name="closeSidepanel" type="function">
  Closes the sidepanel programmatically.
</ResponseField>

## Example with Ref

```jsx theme={null}
import { useRef } from 'react';
import { DocSearchSidepanel } from '@docsearch/react';

function App() {
  const sidepanelRef = useRef(null);

  return (
    <>
      <button onClick={() => sidepanelRef.current?.openSidepanel()}>
        Open AI Chat
      </button>
      <DocSearchSidepanel
        ref={sidepanelRef}
        assistantId="YOUR_ASSISTANT_ID"
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indexName="YOUR_INDEX_NAME"
      />
    </>
  );
}
```

## Keyboard Shortcuts

By default, the sidepanel can be toggled with:

* **Ctrl/Cmd + I**: Toggle sidepanel open/close
* **Escape**: Close sidepanel (when open)

Keyboard shortcuts can be disabled via the `keyboardShortcuts` prop:

```jsx theme={null}
<DocSearchSidepanel
  assistantId="YOUR_ASSISTANT_ID"
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX"
  keyboardShortcuts={{ 'Ctrl/Cmd+I': false }}
/>
```

## Translations

The sidepanel supports comprehensive translations:

```jsx theme={null}
<DocSearchSidepanel
  assistantId="YOUR_ASSISTANT_ID"
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX"
  button={{
    translations: {
      buttonText: 'Chat with AI',
      buttonAriaLabel: 'Open AI assistant'
    }
  }}
  panel={{
    translations: {
      header: {
        newConversationButtonText: 'New Chat',
        conversationHistoryButtonText: 'History'
      },
      promptForm: {
        placeholder: 'Ask a question...',
        sendButtonAriaLabel: 'Send message'
      },
      newConversationScreen: {
        title: 'How can I help you today?',
        suggestedQuestionsTitle: 'Suggested questions'
      }
    }
  }}
/>
```

## Types

### SidepanelButtonProps

```typescript theme={null}
type SidepanelButtonProps = {
  variant?: 'floating' | 'inline';
  translations?: SidepanelButtonTranslations;
};
```

### SidepanelProps

```typescript theme={null}
type SidepanelProps = {
  variant?: 'inline' | 'floating';
  side?: 'left' | 'right';
  pushSelector?: string;
  width?: number | string;
  expandedWidth?: number | string;
  portalContainer?: DocumentFragment | Element | null;
  suggestedQuestions?: boolean;
  translations?: SidepanelTranslations;
  keyboardShortcuts?: SidepanelShortcuts;
};
```

### DocSearchSidepanelProps

```typescript theme={null}
type DocSearchSidepanelProps = DocSearchCallbacks & {
  assistantId: string;
  apiKey: string;
  appId: string;
  indexName: string;
  keyboardShortcuts?: SidepanelShortcuts;
  theme?: DocSearchTheme;
  button?: Omit<SidepanelButtonProps, 'keyboardShortcuts'>;
  panel?: Omit<SidepanelProps, 'keyboardShortcuts'>;
} & SidepanelSearchParameters;
```