Skip to main content
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: 
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: 
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: 
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;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us