DocSearchInstance

Programmatic control interface for DocSearch

The DocSearchInstance interface is returned by the docsearch() function and provides methods and properties for programmatic control of the DocSearch component.

Interface Definition

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

Properties

isReady

isReady · boolean

Returns true once the DocSearch component is mounted and ready for interaction.

This property is true immediately after the component is rendered to the DOM.

Example:

const search = docsearch({ /* config */ });

if (search.isReady) {
  console.log('DocSearch is ready to use');
}

isOpen

isOpen · boolean

Returns true if the search modal is currently open.

Useful for checking modal state before performing actions or syncing UI state with the modal.

Example:

const search = docsearch({ /* config */ });

// Check if modal is open
if (search.isOpen) {
  console.log('Search modal is currently open');
}

// Toggle modal state
function toggleSearch() {
  if (search.isOpen) {
    search.close();
  } else {
    search.open();
  }
}

Methods

open()

open · () => void

Opens the search modal.

If the modal is already open, this method has no effect.

Example:

const search = docsearch({ /* config */ });

// Open modal when clicking a custom button
document.getElementById('search-btn').addEventListener('click', () => {
  search.open();
});

Usage with Custom Triggers:

Button Click

const search = docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_API_KEY',
  indexName: 'docs'
});

// Custom search button
document.querySelector('.custom-search').addEventListener('click', () => {
  search.open();
});

close()

close · () => void

Closes the search modal.

If the modal is already closed, this method has no effect. Automatically refocuses the search button trigger after closing.

Example:

const search = docsearch({ /* config */ });

// Close modal programmatically
function closeSearch() {
  search.close();
}

// Close on custom event
window.addEventListener('route-change', () => {
  if (search.isOpen) {
    search.close();
  }
});

openAskAi()

openAskAi · (initialMessage?: InitialAskAiMessage) => void

Opens Ask AI mode in the modal.

Requires Ask AI to be configured in the docsearch() options via the askAi parameter.

Parameters:

initialMessage · InitialAskAiMessage

Optional initial message to pre-populate the Ask AI interface.

interface InitialAskAiMessage {
  query: string;              // The question or prompt text
  messageId?: string;         // Optional message identifier
  suggestedQuestionId?: string; // Optional suggested question ID
}

Examples:

Basic Usage

const search = docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_API_KEY',
  indexName: 'docs',
  askAi: 'YOUR_ASSISTANT_ID'
});

// Open Ask AI mode
document.getElementById('ask-ai-btn').addEventListener('click', () => {
  search.openAskAi();
});

destroy()

destroy · () => void

Unmounts the DocSearch component and cleans up all resources.

After calling this method:

• The component is removed from the DOM
• All event listeners are cleaned up
• isReady returns false
• All other methods become no-ops

Example:

const search = docsearch({ /* config */ });

// Cleanup when navigating away or unmounting
window.addEventListener('beforeunload', () => {
  search.destroy();
});

// In a SPA framework
function cleanup() {
  search.destroy();
}

Framework Integration Examples:

React

import { useEffect, useRef } from 'react';
import docsearch from '@docsearch/js';

function Search() {
  const searchRef = useRef(null);
  
  useEffect(() => {
    const instance = docsearch({
      container: '#docsearch',
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_API_KEY',
      indexName: 'docs'
    });
    
    searchRef.current = instance;
    
    // Cleanup on unmount
    return () => {
      instance.destroy();
    };
  }, []);
  
  return <div id="docsearch" />;
}

Complete Usage Example

import docsearch from '@docsearch/js';
import '@docsearch/css';

// Initialize DocSearch
const search = docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indexName: 'docs',
  askAi: 'YOUR_ASSISTANT_ID',
  onReady() {
    console.log('DocSearch ready:', search.isReady);
  },
  onOpen() {
    console.log('Modal opened:', search.isOpen);
  },
  onClose() {
    console.log('Modal closed:', !search.isOpen);
  }
});

// Custom search trigger
document.getElementById('custom-search-btn').addEventListener('click', () => {
  search.open();
});

// Custom Ask AI trigger
document.getElementById('ask-ai-btn').addEventListener('click', () => {
  search.openAskAi();
});

// Quick help button
document.getElementById('help-btn').addEventListener('click', () => {
  search.openAskAi({
    query: 'How do I get started?'
  });
});

// Close on route change
window.addEventListener('popstate', () => {
  if (search.isOpen) {
    search.close();
  }
});

// Cleanup before page unload
window.addEventListener('beforeunload', () => {
  search.destroy();
});

// Debug helper
window.docsearch = search; // Access via browser console

TypeScript Types

export interface DocSearchInstance {
  /** Returns true once the component is mounted and ready. */
  readonly isReady: boolean;
  /** Returns true if the modal is currently open. */
  readonly isOpen: boolean;
  /** Opens the search modal. */
  open(): void;
  /** Closes the search modal. */
  close(): void;
  /** Opens Ask AI mode (modal). */
  openAskAi(initialMessage?: InitialAskAiMessage): void;
  /** Unmounts the DocSearch component and cleans up. */
  destroy(): void;
}

export interface InitialAskAiMessage {
  query: string;
  messageId?: string;
  suggestedQuestionId?: string;
}

Related

• docsearch() - Initialize DocSearch
• Getting Started - Installation and basic setup