Référence API

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

JavaScript

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 | requis

Votre identifiant d'application Algolia.

apiKey

type: string | requis

Votre clé API de recherche Algolia.

indices

type: Array<string | DocSearchIndex>

Liste des index et de leurs searchParameters optionnels pour la recherche par mots-clés.

Paramètres de recherche Algolia

astuce

L'ordre de la liste est important car les résultats sont affichés selon la séquence des indices.

Pendant la période de dépréciation de indexName, vous devez fournir soit indices soit indexName. L'absence des deux générera une Error.

JavaScript

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'],
        // ...
      },
    },
  ],
  // ...
});

React

<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 | déprécié

Dépréciation

indexName est actuellement en voie de dépréciation. La nouvelle propriété recommandée est indices.

Le nom de votre index Algolia.

Pendant la période de dépréciation de indexName, vous devez fournir soit indices soit indexName. L'absence des deux générera une Error.

placeholder

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

Texte indicatif affiché dans le champ de recherche de la modale DocSearch. Note : Définir un placeholder remplace le placeholder dynamique basé sur askAi. Il est préférable de modifier les translations.

askAi

type: AskAiObject | string | optionnel

Votre identifiant Algolia Assistant.

JavaScript

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,
  },
  // ...
});

React

<DocSearch
  // ...
  askAi="YOUR_ALGOLIA_ASSISTANT_ID"
/>

in case you want to use different credentials for askAi

<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 prend en charge ces paramètres de recherche essentiels pour des performances optimales :

• Filtrage : facetFilters: ['type:content'] - Filtrer par langue, version ou type de contenu
• Filtrage complexe : filters: 'type:content AND language:en' - Appliquer des règles de filtrage avancées
• Contrôle du contenu : attributesToRetrieve: ['title', 'content', 'url'] - Choisir les attributs récupérés
• Périmètre de recherche : restrictSearchableAttributes: ['title', 'content'] - Limiter la recherche à des champs spécifiques
• Dédoublonnage : distinct: true - Supprimer les résultats en double

Ces paramètres fournissent les fonctionnalités essentielles pour Ask AI tout en conservant une API simple et ciblée.

agentStudio

type: boolean | optionnel | expérimental

Expérimental

agentStudio est actuellement une propriété expérimentale. Elle est prévue pour devenir stable dans la version 5.0.0.

Si agentStudio est true, le chat Ask AI utilisera Agent Studio d'Algolia comme backend de chat à la place du backend Ask AI. En savoir plus dans la documentation d'Algolia Agent Studio.

searchParameters

type: SearchParameters | optionnel | déprécié

Dépréciation

searchParameters est actuellement en voie de dépréciation. La nouvelle propriété recommandée est indices.

Les paramètres de recherche Algolia.

transformItems

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

Reçoit les résultats de recherche avant leur affichage. Doit renvoyer un nouveau tableau de même structure. Utile pour transformer, réorganiser ou filtrer les éléments.

JavaScript

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

React

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

hitComponent

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

Le composant pour afficher chaque élément. Prend en charge les modèles de templates suivants :

• Chaînes HTML avec l'helper html (recommandé pour JS CDN) : ({ hit, children }, { html }) => html...

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

• Templates basés sur des fonctions : (props) => string | JSX.Element | Function

Vous avez accès à l'objet hit qui contient toutes les données du résultat de recherche, et à children qui est le contenu rendu par défaut.

Voir l'implémentation par défaut.

JavaScript

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>
    `;
  },
});

React

<DocSearch
  // ...
  hitComponent={({ hit, children }) => {
    // Using JSX templates
    return (
      <a href={hit.url} className="custom-hit-class">
        <div className="hit-icon">🔍</div>
        <div className="hit-content">{children}</div>
      </a>
    );
  }}
/>

transformSearchClient

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

Utile pour transformer le client de recherche Algolia, par exemple pour débouncer les requêtes.

disableUserPersonalization

type: boolean | default: false | optionnel

Désactive l'enregistrement des recherches récentes et favoris dans le stockage local.

initialQuery

type: string | optionnel

Requête initiale pré-remplie dans le champ de recherche.

navigator

type: Navigator | optionnel

Implémentation de l'API Navigator d'Algolia Autocomplete pour rediriger l'utilisateur lors de l'ouverture d'un lien.

Consultez la documentation de l'API Navigator.

translations

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

Permet de traduire tous les textes bruts et attributs aria présents dans les composants 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 | optionnel

Fonction renvoyant l'URL de votre dépôt de documentation.

JavaScript

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

React

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

Si fournie, un message informatif avec votre lien s'affichera pour les recherches sans résultats. Le texte par défaut est modifiable via la propriété translations.

keyboardShortcuts

type: KeyboardShortcuts | optionnel

Configuration des raccourcis clavier déclenchant l'ouverture du modal de recherche.

Comportement par défaut :

• Ctrl/Cmd+K - Ouvre et ferme le modal de recherche

• / - Ouvre le modal de recherche (ne le ferme pas)

Interface :

interface KeyboardShortcuts {
  'Ctrl/Cmd+K'?: boolean; // default: true
  '/'?: boolean; // default: true
}

JavaScript

// 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 },
});

React

{
  /* 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 }}
/>;

Comportement des raccourcis clavier

• Ctrl/Cmd+K : Raccourci bascule qui ouvre et ferme la modale
• / : Raccourci caractère qui ouvre uniquement la modale (évite les interférences avec la saisie)
• Échap : Ferme toujours la modale indépendamment de la configuration

resultsFooterComponent

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

Le composant à afficher sous les résultats de recherche. Prend en charge les modèles de templates suivants :

• Chaînes HTML avec l'helper html (recommandé pour JS CDN) : ({ state }, { html }) => html...

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

• Templates basés sur des fonctions : (props) => string | JSX.Element | Function

Vous avez accès à l'état actuel qui permet de récupérer le nombre de résultats, la requête, etc.

JavaScript

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>
    `;
  },
});

React

<DocSearch
  // ...
  resultsFooterComponent={({ state }) => {
    // Using JSX templates
    return (
      <div className="DocSearch-HitsFooter">
        <a href="https://docsearch.algolia.com/apply" target="_blank">
          See all {state.context.nbHits} results
        </a>
      </div>
    );
  }}
/>

maxResultsPerGroup

type: number | optional

Nombre maximum de résultats à afficher par groupe de recherche. Par défaut : 5.

Exemple fonctionnel sans JSX dans ce bac à sable

JavaScript

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

recentSearchesLimit

type: number | default: 7 | optionnel

Nombre maximum de recherches récentes mémorisées pour l'utilisateur. Valeur par défaut : 7.

JavaScript

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

React

<DocSearch
  // ...
  recentSearchesLimit={12}
  // ...
/>

recentSearchesWithFavoritesLimit

type: number | default: 4 | optionnel

Nombre maximum de recherches récentes conservées lorsque l'utilisateur a des favoris. Valeur par défaut : 4.

JavaScript

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

React

<DocSearch
  // ...
  recentSearchesWithFavoritesLimit={5}
  // ...
/>

portalContainer (React uniquement)

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

Élément où le modal DocSearch sera injecté. À utiliser pour un rendu dans un nœud DOM spécifique (shadow root, conteneur de layout, gestionnaire de modals). Par défaut, le modal s'injecte dans document.body.

avertissement

Cette prop n'existe que dans @docsearch/react. Si vous utilisez @docsearch/js, utilisez plutôt l'option container - la valeur fournie sert à la fois de point de montage pour le bouton de recherche et de cible du portail pour la modale.

React

// 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}
/>;

JavaScript

docsearch({
  // the element that will **contain the button** and **host the modal portal**
  container: '#modal-root',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indexName: 'YOUR_INDEX_NAME',
});