Saltar al contenido principal
Versión: Estable (v4.x)

Referencia de la API

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

container​

type: string | HTMLElement | required

The container for the DocSearch search box. You can either pass a CSS selector or an Element. If there are several containers matching the selector, DocSearch picks up the first one.

environment​

type: typeof window | default: window | optional

The environment in which your application is running.

This is useful if you’re using DocSearch in a different context than window.

appId​

type: string | requerido

Tu ID de aplicación de Algolia.

apiKey​

type: string | requerido

Tu clave de la API de búsqueda de Algolia.

indices​

type: Array<string | DocSearchIndex>

Lista de índices y sus searchParameters opcionales para búsqueda por palabras clave.

Parámetros de búsqueda de Algolia

consejo

El orden en la lista es importante ya que los resultados se ordenan según el orden de indices.

Mientras indexName está en desuso, es obligatorio pasar indices o indexName. Si no se proporciona ninguno, se lanzará un Error.

docsearch({
  // ...
  indices: ['YOUR_ALGOLIA_INDEX'],
  // ...
});

in case you want to use custom searchParameters for the index

docsearch({
  // ...
  indices: [
    {
      name: 'YOUR_ALGOLIA_INDEX',
      searchParameters: {
        facetFilters: ['language:en'],
        // ...
      },
    },
  ],
  // ...
});

indexName​

type: string | obsoleto

Advertencia de obsolescencia

Actualmente se planea dejar obsoleto indexName. La propiedad recomendada es indices.

Nombre de tu índice de Algolia.

Mientras indexName está en desuso, es obligatorio pasar indices o indexName. Si no se proporciona ninguno, se lanzará un Error.

placeholder​

type: string | default: "Search docs" | opcional

Placeholder del input en el modal emergente de DocSearch. Nota: Si añades un placeholder, reemplazará el placeholder dinámico basado en askAi. Es mejor editar las traducciones.

askAi​

type: AskAiObject | string | opcional

Tu ID de Asistente de Algolia.

docsearch({
  // ...
  askAi: 'YOUR_ALGOLIA_ASSISTANT_ID',
  // ...
});

or if you want to use different credentials for askAi and add search parameters

docsearch({
  // ...
  askAi: {
    indexName: 'ANOTHER_INDEX_NAME',
    apiKey: 'ANOTHER_SEARCH_API_KEY',
    appId: 'ANOTHER_APP_ID',
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      // Filtering parameters
      facetFilters: ['language:en', 'version:latest'],
      filters: 'type:content AND language:en',

      // Content control parameters
      attributesToRetrieve: ['title', 'content', 'url'],
      restrictSearchableAttributes: ['title', 'content'],

      // Deduplication
      distinct: true,
    },

    // Enables/disables showing suggested questions on Ask AI's new conversation screen
    // NOTE: Only available with version >= 4.3
    suggestedQuestions: true,
  },
  // ...
});
Ask AI admite estos parámetros de búsqueda esenciales para rendimiento óptimo:
  • Filtrado: facetFilters: ['type:content'] - Filtrar por idioma, versión o tipo de contenido
  • Filtrado complejo: filters: 'type:content AND language:en' - Aplicar reglas de filtrado avanzadas
  • Control de contenido: attributesToRetrieve: ['title', 'content', 'url'] - Controlar qué atributos se recuperan
  • Ámbito de búsqueda: restrictSearchableAttributes: ['title', 'content'] - Limitar búsqueda a campos específicos
  • Desduplicación: distinct: true - Eliminar resultados duplicados

Estos parámetros proporcionan la funcionalidad esencial para Ask AI manteniendo la API simple y enfocada.

agentStudio​

type: boolean | opcional | experimental

Experimental

agentStudio es actualmente una propiedad experimental. Está previsto que sea estable en la versión 5.0.0.

Si agentStudio es true, el chat de Ask AI utilizará Agent Studio de Algolia como backend de chat en lugar del backend de Ask AI. Más información en la documentación de Algolia Agent Studio.

searchParameters​

type: SearchParameters | opcional | obsoleto

Advertencia de obsolescencia

Actualmente se planea dejar obsoleto searchParameters. La propiedad recomendada es indices.

Los Parámetros de búsqueda de Algolia.

transformItems​

type: function | default: items => items | opcional

Recibe los resultados de búsqueda antes de mostrarlos. Debe devolver un nuevo array con la misma estructura. Útil para transformar, eliminar o reordenar elementos.

docsearch({
  // ...
  transformItems(items) {
    return items.map((item) => ({
      ...item,
      content: item.content.toUpperCase(),
    }));
  },
});

hitComponent​

type: ({ hit, children }, { html }) => JSX.Element | string | Function | default: Hit | opcional

Componente para mostrar cada elemento. Admite patrones de plantilla:

  • Cadenas HTML con helper html (recomendado para JS CDN): ({ hit, children }, { html }) => html...

  • Plantillas JSX (para React/Preact): ({ hit, children }) => <div>...</div>

  • Plantillas basadas en funciones: (props) => string | JSX.Element | Function

Tienes acceso al objeto hit que contiene todos los datos del resultado de búsqueda, y children que es el contenido renderizado por defecto.

Consulta la implementación por defecto.

docsearch({
  // ...
  hitComponent({ hit, children }, { html }) {
    // Using HTML strings with html helper
    return html`
      <a href="${hit.url}" class="custom-hit-class">
        <div class="hit-icon">🔍</div>
        <div class="hit-content">${children}</div>
      </a>
    `;
  },
});

transformSearchClient​

type: function | default: DocSearchTransformClient => DocSearchTransformClient | opcional

Útil para transformar el Cliente de búsqueda de Algolia, por ejemplo para debouncear consultas de búsqueda

disableUserPersonalization​

type: boolean | default: false | optional

Desactiva el guardado de búsquedas recientes y favoritos en el almacenamiento local.

initialQuery​

type: string | optional

Consulta inicial del campo de búsqueda.

type: Navigator | optional

Implementación de la API Navigator de Algolia Autocomplete para redirigir al usuario al abrir un enlace.

Más información en la documentación de la API Navigator.

translations​

type: Partial<DocSearchTranslations> | default: docSearchTranslations | optional

Permite traducir cualquier texto y etiquetas aria-labels presentes en el botón o componentes modales de DocSearch.

docSearchTranslations
const translations: DocSearchTranslations = {
  button: {
    buttonText: 'Search',
    buttonAriaLabel: 'Search',
  },
  modal: {
    searchBox: {
      clearButtonTitle: 'Clear',
      clearButtonAriaLabel: 'Clear the query',
      closeButtonText: 'Close',
      closeButtonAriaLabel: 'Close',
      placeholderText: undefined, // fallback: 'Search docs' or 'Search docs or ask AI a question'
      placeholderTextAskAi: undefined, // fallback: 'Ask another question...'
      placeholderTextAskAiStreaming: 'Answering...',
      // can only be one of the following
      // https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/enterkeyhint#value
      enterKeyHint: 'search',
      enterKeyHintAskAi: 'enter',
      searchInputLabel: 'Search',
      backToKeywordSearchButtonText: 'Back to keyword search',
      backToKeywordSearchButtonAriaLabel: 'Back to keyword search',
      newConversationPlaceholder: 'Ask a question',
      conversationHistoryTitle: 'My conversation history',
      startNewConversationText: 'Start a new conversation',
      viewConversationHistoryText: 'Conversation history'
    },
    startScreen: {
      recentSearchesTitle: 'Recent',
      noRecentSearchesText: 'No recent searches',
      saveRecentSearchButtonTitle: 'Save this search',
      removeRecentSearchButtonTitle: 'Remove this search from history',
      favoriteSearchesTitle: 'Favorite',
      removeFavoriteSearchButtonTitle: 'Remove this search from favorites',
      recentConversationsTitle: 'Recent conversations',
      removeRecentConversationButtonTitle:
        'Remove this conversation from history',
    },
    errorScreen: {
      titleText: 'Unable to fetch results',
      helpText: 'You might want to check your network connection.',
    },
    noResultsScreen: {
      noResultsText: 'No results found for',
      suggestedQueryText: 'Try searching for',
      reportMissingResultsText: 'Believe this query should return results?',
      reportMissingResultsLinkText: 'Let us know.',
    },
    resultsScreen: {
      askAiPlaceholder: 'Ask AI: ',
      noResultsAskAiPlaceholder: 'Didn't find it in the docs? Ask AI to help: ',
    },
    askAiScreen: {
      disclaimerText:
        'Answers are generated with AI which can make mistakes. Verify responses.',
      relatedSourcesText: 'Related sources',
      thinkingText: 'Thinking...',
      copyButtonText: 'Copy',
      copyButtonCopiedText: 'Copied!',
      copyButtonTitle: 'Copy',
      likeButtonTitle: 'Like',
      dislikeButtonTitle: 'Dislike',
      thanksForFeedbackText: 'Thanks for your feedback!',
      preToolCallText: 'Searching...',
      duringToolCallText: 'Searching for ',
      afterToolCallText: 'Searched for',
      // If provided, these override the default rendering of aggregated tool calls:
      aggregatedToolCallNode: undefined, // (queries: string[], onSearchQueryClick: (query: string) => void) => React.ReactNode
      aggregatedToolCallText: undefined, // (queries: string[]) => { before?: string; separator?: string; lastSeparator?: string; after?: string }
      // Text to show when user has stopped streaming a message
      stoppedStreamingText: 'You stopped this response',
    },
    footer: {
      selectText: 'Select',
      submitQuestionText: 'Submit question',
      selectKeyAriaLabel: 'Enter key',
      navigateText: 'Navigate',
      navigateUpKeyAriaLabel: 'Arrow up',
      navigateDownKeyAriaLabel: 'Arrow down',
      closeText: 'Close',
      backToSearchText: 'Back to search',
      closeKeyAriaLabel: 'Escape key',
      poweredByText: 'Powered by',
    },
    newConversation: {
      newConversationTitle: 'How can I help you today?',
      newConversationDescription: 'I search through your documentation to help you find setup guides, feature details and troubleshooting tips, fast.'
    }
  },
};

getMissingResultsUrl​

type: ({ query: string }) => string | optional

Función que devuelve la URL de tu repositorio de documentación.

docsearch({
  // ...
  getMissingResultsUrl({ query }) {
    return `https://github.com/algolia/docsearch/issues/new?title=${query}`;
  },
});

Cuando se proporciona, se mostrará un mensaje informativo con tu enlace en búsquedas sin resultados. El texto predeterminado puede cambiarse mediante la propiedad translations.

No results screen with informative message

keyboardShortcuts​

type: KeyboardShortcuts | optional

Configuración de atajos de teclado que activan el modal de búsqueda.

Comportamiento predeterminado:​

  • Ctrl/Cmd+K - Abre y cierra el modal de búsqueda

  • / - Abre el modal de búsqueda (no lo cierra)

Interfaz:​

interface KeyboardShortcuts {
  'Ctrl/Cmd+K'?: boolean; // default: true
  '/'?: boolean; // default: true
}
// Default - all shortcuts enabled
docsearch({
  // ...
});

// Disable slash shortcut
docsearch({
  // ...
  keyboardShortcuts: { '/': false },
});

// Disable Ctrl/Cmd+K shortcut (also hides button hint)
docsearch({
  // ...
  keyboardShortcuts: { 'Ctrl/Cmd+K': false },
});

// Disable all keyboard shortcuts
docsearch({
  // ...
  keyboardShortcuts: { 'Ctrl/Cmd+K': false, '/': false },
});
Comportamiento de atajos de teclado
  • Ctrl/Cmd+K: Atajo de alternancia que abre y cierra el modal
  • /: Atajo de carácter que solo abre el modal (evita interferir con la escritura de búsquedas)
  • Escape: Siempre cierra el modal independientemente de la configuración

resultsFooterComponent​

type: ({ state }, { html }) => JSX.Element | string | Function | opcional

Componente para mostrar debajo de los resultados de búsqueda. Admite patrones de plantilla:

  • Cadenas HTML con helper html (recomendado para JS CDN): ({ state }, { html }) => html...

  • Plantillas JSX (para React/Preact): ({ state }) => <div>...</div>

  • Plantillas basadas en funciones: (props) => string | JSX.Element | Function

Tienes acceso al estado actual que te permite obtener el número de resultados devueltos, la consulta, etc.

docsearch({
  // ...
  resultsFooterComponent({ state }, { html }) {
    // Using HTML strings with html helper
    return html`
      <div class="DocSearch-HitsFooter">
        <a href="https://docsearch.algolia.com/apply" target="_blank">
          See all ${state.context.nbHits} results
        </a>
      </div>
    `;
  },
});

maxResultsPerGroup​

type: number | opcional

Número máximo de resultados a mostrar por grupo de búsqueda. Por defecto es 5.

Puedes encontrar un ejemplo funcional sin JSX en este sandbox

docsearch({
  // ...
  maxResultsPerGroup: 7,
});

recentSearchesLimit​

type: number | default: 7 | opcional

Número máximo de búsquedas recientes almacenadas para el usuario. Por defecto es 7.

docsearch({
  // ...
  recentSearchesLimit: 12,
  // ...
});

recentSearchesWithFavoritesLimit​

type: number | default: 4 | opcional

Número máximo de búsquedas recientes almacenadas cuando el usuario tiene búsquedas favoritas. Por defecto es 4.

docsearch({
  // ...
  recentSearchesWithFavoritesLimit: 5,
  // ...
});

portalContainer (solo React)​

type: Element | DocumentFragment | default: document.body | opcional

Elemento donde se portalizará el modal de DocSearch. Úsalo cuando necesites que el overlay se renderice en un nodo DOM personalizado (por ejemplo en shadow roots, contenedores de layout específicos o gestores modales). Si se omite, el modal se portaliza en document.body.

advertencia

Esta propiedad solo existe en @docsearch/react. Si usas @docsearch/js, usa la opción container en su lugar: el valor que pases será tanto el punto de montaje del botón de búsqueda como el destino del portal para el modal.

// assume you have a dedicated modal root in your html
<div id="modal-root" />;

const portalEl = document.getElementById('modal-root');

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  // render the modal inside #modal-root instead of document.body
  portalContainer={portalEl}
/>;