Skip to main content
Version: Stable (v5.x)

Sidepanel JS API reference

sidepanel​

function sidepanel(props: SidepanelProps): SidepanelInstance;

The function resolves container, mounts the component, and returns immediately. Use onReady or instance.isReady to detect the mounted state.

Mounting props​

container​

type: HTMLElement | string | required

Element or CSS selector that receives the Sidepanel application.

environment​

type: typeof window | optional

Environment used to resolve a selector. Defaults to the browser window. A selector without a browser environment throws.

The function throws if a selector doesn't match an element.

Connection props​

appId​

type: string | required

Algolia application ID.

apiKey​

type: string | required

Public API key with search permission.

assistantId​

type: string | required

Agent Studio agent ID.

indexName​

type: string | required

Primary index for Agent Studio and conversation storage.

The public SidepanelProps type in 5 doesn't include the React Sidepanel's top-level searchParameters field.

UI props​

theme​

type: 'light' | 'dark' | optional

Sets data-theme on the document root while mounted.

keyboardShortcuts​

type: { 'Ctrl/Cmd+I'?: boolean } | optional

Enables or disables the Sidepanel shortcut. The shortcut is enabled by default.

button​

type: SidepanelButtonProps | optional

Configures the built-in button. Defaults to {}.

button accepts variant: 'floating' | 'inline' and translations.buttonText or translations.buttonAriaLabel.

panel​

type: SidepanelPanelProps | optional

Configures layout, suggested questions, and translations. Defaults to {}.

panel accepts variant, side, pushSelector, width, expandedWidth, portalContainer, suggestedQuestions, translations, tools, memory, and indices. Panel-level tools, memory, and indices override their root values. Don't set panel.keyboardShortcuts; configure shortcuts at the root.

Callbacks​

onReady​

type: () => void | optional

Runs once after the component mounts.

onOpen​

type: () => void | optional

Runs when the Sidepanel opens.

onClose​

type: () => void | optional

Runs when the Sidepanel closes.

Use these Sidepanel-specific callbacks rather than the inherited React provider callback names.

Agent Studio options​

tools​

type: Record<string, ToolDefinition> | optional

Handles and renders custom Agent Studio tools. Defaults to {}.

memory​

type: { enabled?: boolean; userToken?: string } | optional

Configures memory-tool rendering and authentication.

indices​

type: string[] | optional

Index names available to Agent Studio. Put descriptions and tool defaults on the agent configuration. Put per-index runtime overrides in searchParameters.

These fields are root props:

load-sidepanel.js
const assistant = sidepanel({
  container: '#docsearch-sidepanel',
  appId: 'YOUR_APPLICATION_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  assistantId: 'YOUR_AGENT_ID',
  indexName: 'docs',
  memory: {
    enabled: true,
    userToken: userMemoryToken,
  },
  indices: ['docs', 'support_articles'],
  searchParameters: {
    docs: { filters: 'version:v5' },
    support_articles: { filters: 'visibility:public' },
  },
  tools: {
    getReleaseChannel: {
      async onToolCall({ input, addToolOutput }) {
        const channel = await readReleaseChannel(input);
        await addToolOutput({ output: { channel } });
      },
      render({ message }) {
        return `Release channel: ${message.output.channel}`;
      },
    },
  },
});

ToolDefinition requires render({ message: { input, output } }), which returns a string. It can also define onToolCall and translations.callingToolText. If you handle a client-side tool, call addToolOutput.

Generate memory.userToken on your server. The package sends it as x-algolia-secure-user-token.

SidepanelInstance​

Calls to open and close before the internal ref is ready are no-ops.

InitialAskAiMessage is:

types.ts
type InitialAskAiMessage = {
  query: string;
  messageId?: string;
  suggestedQuestionId?: string;
};

isReady​

type: readonly boolean

Whether the component is mounted.

isOpen​

type: readonly boolean

Whether the panel is open.

open​

type: (initialMessage?: InitialAskAiMessage) => void

Opens the panel, optionally with a question or stored-message IDs.

close​

type: () => void

Closes the panel.

destroy​

type: () => void

Unmounts the component and marks the instance not ready.

Exports​

@docsearch/sidepanel-js has one value export: the default sidepanel function.

It also exports the SidepanelProps, SidepanelInstance, and SidepanelCallbacks TypeScript types. It doesn't provide a named sidepanel export or package subpaths.

load-sidepanel.ts
import sidepanel, {
  type SidepanelCallbacks,
  type SidepanelInstance,
  type SidepanelProps,
} from '@docsearch/sidepanel-js';