DOCSEARCHbyAlgolia
Submit Docs

Algolia SiteSearch

repository·main·Indexed 11 days ago

https://github.com/algolia/sitesearch

Opinionated, ready-to-use search experiences and components powered by Algolia's InstantSearch and Ask AI. Supports React and Vanilla JavaScript integrations with features like AI-driven conversational search, WCAG 2.1 AA compliant accessibility, and CSS variable-based theming. Includes specialized experiences such as Dropdown Search, Sidepanel Ask AI, and Highlight to AskAI.

Tokens
15.8K
Snippets
41
Records
67
Agent score
47%

What's inside Algolia SiteSearch

  1. Explore the documentation project structure

    main

    The documentation application is built with Next.js and Fumadocs. Key files and routes include:

    • lib/source.ts: Contains the code for the content source adapter. The loader() function provides the interface to access your content.
    • lib/layout.shared.tsx: Contains shared options for layouts.
    • app/(home): Route group for the landing page and other top-level pages.
    • app/docs: The main documentation layout and pages.
    • app/api/search/route.ts: The Route Handler responsible for search functionality.

  2. Get started with Algolia SiteSearch

    main

    Algolia SiteSearch provides opinionated, high-performance search components powered by Algolia's InstantSearch and Ask AI. It is available as both React implementations and Vanilla JavaScript bundles, making it suitable for modern web applications.

    Key features include:

    • Instant search: Sub-50ms search performance.
    • AI-enhanced: Conversational chat interface via Ask AI.
    • Accessible: WCAG 2.1 AA compliant with keyboard navigation.
    • Extensible: Comprehensive CSS theming system.

  3. Dropdown Search behavior and interaction

    main

    The Dropdown Search experience follows these interaction patterns:

    • Automatic Opening: The dropdown appears automatically when the query length is greater than 0.
    • Outside Click: The dropdown closes automatically when clicking outside, handled by Radix Popover.
    • Selection: Selecting a result closes the dropdown and clears the current query.
    • Keyboard Navigation: Users can navigate results using the arrow keys and select an item using the Enter key.
    • Layout: The component stays inline with your layout and does not trigger a modal overlay.

  4. Search experience keyboard shortcuts and behavior

    main

    The Search experience is designed for accessibility and speed:

    • Open Modal: Press Cmd+K (Mac) or Ctrl+K (Windows).
    • Navigation: Use arrow keys to move through results.
    • Selection: Press Enter to select a result.
    • Dismiss: Press Escape to close the search modal.
    • Accessibility: Includes full keyboard support and ARIA labels for screen readers.

  5. Transform search items with transformItems

    main

    The transformItems option is a lifecycle hook that allows you to intercept and modify the array of search results before they are passed to the rendering engine.

    Common use cases include:

    • Image Proxying: Modifying image URLs to bypass CORS or use a specific CDN.
    • Data Formatting: Converting raw data (like dates or prices) into human-readable strings.
    • Field Mapping: Adding computed properties to the items.
    transformItems: (items) => 
  items.map(item => ({
    ...item,
    image: item.image ? `https://your-proxy.com/${item.image}` : item.image
  }))

  6. Sidepanel Ask AI behavior and accessibility

    main

    The Sidepanel Ask AI experience is designed to be non-blocking and accessible:

    • Triggering: Users can open the panel by clicking the "Ask AI" button or using keyboard shortcuts: Cmd+I (Mac) or Ctrl+I (Windows).
    • Interaction: The rest of the page remains interactive while the panel is open. The chat automatically scrolls to show new messages.
    • Closing: Press Escape to close the sidepanel.
    • Sizing: On desktop, the panel is resizable between a default of 360px and a maximum of 580px. On mobile, it displays as a full-width interface.
    • Keyboard Navigation: Users can press Enter to send messages.

  7. Quickstart: Install and initialize @algolia/sitesearch via CDN

    main

    You can use @algolia/sitesearch without a build step by including the CSS and JS bundles from unpkg. The UMD bundle exposes the window.SiteSearch object.

    To use it, add a container element to your HTML, include the assets, and call window.SiteSearch.init() with your Algolia credentials and configuration.

    <!-- CSS -->
<link rel="stylesheet" href="https://unpkg.com/@algolia/sitesearch@1/dist/search.min.css" />

<!-- JS (UMD exposes window.SiteSearch) -->
<script src="https://unpkg.com/@algolia/sitesearch@1/dist/search.min.js"></script>

<div id="search-root"></div>

<script>
  window.SiteSearch.init({
    container: '#search-root',
    applicationId: 'ALGOLIA_APP_ID',
    apiKey: 'ALGOLIA_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    // Optional UX tweaks
    placeholder: 'What are you looking for?',
    hitsPerPage: 8,
    keyboardShortcut: 'cmd+k',
    darkMode: undefined,
    attributes: {
      primaryText: 'title',
      secondaryText: 'description',
      tertiaryText: 'itunesAuthor',
      url: 'url',
      image: 'image',
    },
    transformItems: (items) => 
      items.map(item => ({
        ...item,
        image: item.image ? `https://your-proxy.com/${item.image}` : item.image
      }))
  });
</script>

  8. Quickstart SiteSearch with Vanilla JS

    main

    You can use the vanilla version of SiteSearch in any project by including the CDN bundles for CSS and JavaScript. To implement the search experience, you need to provide a container element and an configuration object via SiteSearch.init().

    Required configuration keys include:

    • container: The CSS selector for the element where the search UI will be rendered.
    • applicationId: Your Algolia Application ID.
    • apiKey: Your Algolia API Key.
    • indexName: The name of your Algolia index.
    • attributes: An object mapping UI fields to your index attributes:
      • primaryText: The attribute to display as the main title in the hits list.
      • secondaryText: The secondary attribute for hits.
      • tertiaryText: The tertiary attribute for hits.
      • url: The attribute containing the hit's URL.
      • image: The attribute containing the hit's image URL.
    <link rel="stylesheet" href="https://unpkg.com/@algolia/sitesearch@latest/dist/search.min.css" />
<script src="https://unpkg.com/@algolia/sitesearch@latest/dist/search.min.js"></script>
<div id="search"></div>
<script>
  SiteSearch.init({
    container: "#search",
    applicationId: "YOUR_APP_ID",
    apiKey: "YOUR_API_KEY",
    indexName: "YOUR_INDEX_NAME",
    attributes: {
      primaryText: "title",
      secondaryText: "description",
      tertiaryText: "itunesAuthor",
      url: "url",
      image: "imageUrl",
    },
  });
</script>

  12. Prerequisites for Algolia SiteSearch

    main

    Before using SiteSearch, ensure you have the following Algolia resources ready:

    • An Algolia account.
    • An Algolia index containing the data you want to search.
    • An Algolia API key for authentication.
    • Algolia Ask AI assistant (optional): Required only if you intend to implement conversational search features.