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

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

Usage

Basic Usage

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"
    />
  );
}

Props

Required Props

assistantId · string · required

The assistant ID to use for the Ask AI feature.

apiKey · string · required

Public API key with search permissions for the index.

appId · string · required

Algolia application ID used by the search client.

indexName · string · required

The index name to use for the Ask AI feature. Your assistant will search this index for relevant documents.

Configuration

keyboardShortcuts · 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

theme · 'light' | 'dark' · default: "'light'"

Theme overrides applied to the Sidepanel button and panel.

searchParameters · 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.

agentStudio · 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.

Button Configuration

button · 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.

Panel Configuration

panel · 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

Callbacks

onReady · () => void

Callback fired when the component is ready.

onOpen · () => void

Callback fired when the modal or sidepanel opens.

onClose · () => void

Callback fired when the modal or sidepanel closes.

onSidepanelOpen · () => void

Callback fired specifically when the sidepanel opens.

onSidepanelClose · () => void

Callback fired specifically when the sidepanel closes.

Button Variants

Floating Button (default)

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

<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:

<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:

<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:

<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:

openModal · function

Opens the search modal (if integrated with DocSearch).

closeModal · function

Closes the search modal (if integrated with DocSearch).

openSidepanel · function

Opens the sidepanel programmatically.

closeSidepanel · function

Closes the sidepanel programmatically.

Example with Ref

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:

<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:

<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

type SidepanelButtonProps = {
  variant?: 'floating' | 'inline';
  translations?: SidepanelButtonTranslations;
};

SidepanelProps

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

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