sidepanel() - JavaScript Sidepanel API

API reference for the @docsearch/sidepanel-js package

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

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

Related

• DocSearchSidepanel (React) - React component version
• Ask AI Configuration - Configure the Ask AI assistant
• Getting Started - Installation and basic setup