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

# 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

<CodeGroup>
  ```bash npm theme={null}
  npm install @docsearch/sidepanel-js
  ```

  ```bash yarn theme={null}
  yarn add @docsearch/sidepanel-js
  ```

  ```bash pnpm theme={null}
  pnpm add @docsearch/sidepanel-js
  ```
</CodeGroup>

You can also use the CDN version:

```html theme={null}
<script src="https://cdn.jsdelivr.net/npm/@docsearch/sidepanel-js@4"></script>
```

## sidepanel()

Initializes and mounts a DocSearch Ask AI sidepanel component.

### Syntax

```typescript theme={null}
function sidepanel(props: SidepanelProps): SidepanelInstance
```

### Parameters

<ParamField path="container" type="string | HTMLElement" required>
  The DOM element or CSS selector where the sidepanel will be mounted.
</ParamField>

<ParamField path="appId" type="string" required>
  Your Algolia application ID.
</ParamField>

<ParamField path="apiKey" type="string" required>
  Your Algolia search-only API key.
</ParamField>

<ParamField path="askAi" type="string | DocSearchAskAi" required>
  Ask AI configuration. Can be a simple assistant ID string or a full configuration object.
</ParamField>

<ParamField path="indices" type="Array<string | DocSearchIndex>">
  Array of Algolia index names to search. Can be strings or objects with index name and search parameters.
</ParamField>

<ParamField path="variant" type="'floating' | 'inline'" default="floating">
  Display variant for the sidepanel:

  * `floating`: Overlays on the right side of the page
  * `inline`: Embedded in the page layout
</ParamField>

<ParamField path="placeholder" type="string">
  Placeholder text for the search input.
</ParamField>

<ParamField path="theme" type="'light' | 'dark'">
  Theme mode for the sidepanel UI.
</ParamField>

<ParamField path="translations" type="object">
  Localized strings for the sidepanel UI. See [Translations](/api/translations) for all available strings.
</ParamField>

<ParamField path="onReady" type="() => void">
  Callback invoked when the sidepanel is mounted and ready for interaction.
</ParamField>

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

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

<ParamField path="environment" type="Window">
  Custom window object for SSR environments. Defaults to global `window`.
</ParamField>

### Return Value

Returns a [SidepanelInstance](#sidepanelinstance) object with methods and properties for programmatic control.

### Examples

#### Basic Usage

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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

<ResponseField name="isReady" type="boolean">
  Returns `true` once the component is mounted and ready for interaction. Read-only.
</ResponseField>

<ResponseField name="isOpen" type="boolean">
  Returns `true` if the sidepanel is currently open. Read-only.
</ResponseField>

### Methods

<ResponseField name="open" type="(initialMessage?: InitialAskAiMessage) => void">
  Opens the sidepanel. Optionally accepts an initial message to start a conversation.

  ```typescript theme={null}
  interface InitialAskAiMessage {
    type: 'suggested-question' | 'prompt';
    prompt: string;
  }
  ```
</ResponseField>

<ResponseField name="close" type="() => void">
  Closes the sidepanel.
</ResponseField>

<ResponseField name="destroy" type="() => void">
  Unmounts the sidepanel component and cleans up all resources. Call this when removing the sidepanel from your application.
</ResponseField>

### Usage Examples

#### Open with Initial Question

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

#### Check State

```javascript theme={null}
if (instance.isReady && !instance.isOpen) {
  instance.open();
}
```

#### Clean Up

```javascript theme={null}
// When removing the sidepanel
instance.destroy();
```

## TypeScript Types

```typescript theme={null}
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)](/api/docsearch-sidepanel) - React component version
* [Ask AI Configuration](/api/types/ask-ai-config) - Configure the Ask AI assistant
* [Getting Started](/quickstart) - Installation and basic setup