DocSearchSidepanel

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

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:

Opens the search modal (if integrated with DocSearch).

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;
};