Skip to main content
The @docsearch/sidepanel-js package provides a vanilla JavaScript implementation of the DocSearch Ask AI sidepanel. This package is ideal for non-React applications that want to add AI-powered search assistance to their documentation.

​
Installation

npm install @docsearch/sidepanel-js
You can also use the CDN version: 
<script src="https://cdn.jsdelivr.net/npm/@docsearch/sidepanel-js@4"></script>

​
sidepanel()

Initializes and mounts a DocSearch Ask AI sidepanel component.

​
Syntax

function sidepanel(props: SidepanelProps): SidepanelInstance

​
Parameters

​
container
string | HTMLElement
required
The DOM element or CSS selector where the sidepanel will be mounted.
​
appId
string
required
Your Algolia application ID.
​
apiKey
string
required
Your Algolia search-only API key.
​
askAi
string | DocSearchAskAi
required
Ask AI configuration. Can be a simple assistant ID string or a full configuration object.
​
indices
Array<string | DocSearchIndex>
Array of Algolia index names to search. Can be strings or objects with index name and search parameters.
​
variant
'floating' | 'inline'
default:"floating"
Display variant for the sidepanel:
  • floating: Overlays on the right side of the page
  • inline: Embedded in the page layout
​
placeholder
string
Placeholder text for the search input.
​
theme
'light' | 'dark'
Theme mode for the sidepanel UI.
​
translations
object
Localized strings for the sidepanel UI. See Translations for all available strings.
​
onReady
() => void
Callback invoked when the sidepanel is mounted and ready for interaction.
​
onOpen
() => void
Callback invoked when the sidepanel opens.
​
onClose
() => void
Callback invoked when the sidepanel closes.
​
environment
Window
Custom window object for SSR environments. Defaults to global window.

​
Return Value

Returns a SidepanelInstance object with methods and properties for programmatic control.

​
Examples

​
Basic Usage

import sidepanel from '@docsearch/sidepanel-js';

const instance = sidepanel({
  container: '#sidepanel-container',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: ['YOUR_INDEX_NAME'],
  askAi: 'YOUR_ASSISTANT_ID',
});

​
With Lifecycle Callbacks

const instance = sidepanel({
  container: '#sidepanel-container',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: ['YOUR_INDEX_NAME'],
  askAi: 'YOUR_ASSISTANT_ID',
  onReady: () => {
    console.log('Sidepanel is ready');
  },
  onOpen: () => {
    console.log('Sidepanel opened');
  },
  onClose: () => {
    console.log('Sidepanel closed');
  },
});

​
Inline Variant

const instance = sidepanel({
  container: '#docs-sidebar',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: ['YOUR_INDEX_NAME'],
  askAi: 'YOUR_ASSISTANT_ID',
  variant: 'inline',
});

​
With Custom Theme and Translations

const instance = sidepanel({
  container: '#sidepanel-container',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: ['YOUR_INDEX_NAME'],
  askAi: 'YOUR_ASSISTANT_ID',
  theme: 'dark',
  translations: {
    button: {
      buttonText: 'Ask AI',
      buttonAriaLabel: 'Open AI assistant',
    },
    modal: {
      searchBox: {
        askAiPlaceholder: 'Ask a question...',
      },
    },
  },
});

​
SidepanelInstance

The interface returned by sidepanel() provides methods and properties for controlling the sidepanel programmatically.

​
Properties

​
isReady
boolean
Returns true once the component is mounted and ready for interaction. Read-only.
​
isOpen
boolean
Returns true if the sidepanel is currently open. Read-only.

​
Methods

​
open
(initialMessage?: InitialAskAiMessage) => void
Opens the sidepanel. Optionally accepts an initial message to start a conversation.
interface InitialAskAiMessage {
  type: 'suggested-question' | 'prompt';
  prompt: string;
}
​
close
() => void
Closes the sidepanel.
​
destroy
() => void
Unmounts the sidepanel component and cleans up all resources. Call this when removing the sidepanel from your application.

​
Usage Examples

​
Open with Initial Question

instance.open({
  type: 'prompt',
  prompt: 'How do I get started with DocSearch?',
});

​
Check State

if (instance.isReady && !instance.isOpen) {
  instance.open();
}

​
Clean Up

// When removing the sidepanel
instance.destroy();

​
TypeScript Types

interface SidepanelInstance {
  readonly isReady: boolean;
  readonly isOpen: boolean;
  open(initialMessage?: InitialAskAiMessage): void;
  close(): void;
  destroy(): void;
}

interface SidepanelCallbacks {
  onReady?: () => void;
  onOpen?: () => void;
  onClose?: () => void;
}

type SidepanelProps = DocSearchSidepanelProps & SidepanelCallbacks & {
  container: HTMLElement | string;
  environment?: typeof window;
};

Build docs developers (and LLMs) love

Get started for freeTalk to us