Atri AI Documentation

Overview

The @atri-ai/templates package provides production-ready React search components that can be easily integrated into any React application. With full TypeScript support and customizable styling, these components offer the fastest path to adding AI-powered search to your React projects.

Installation

Install the package via npm in your React project:

npm install @atri-ai/templates

Component Parameters

Required Parameters

projectIdstring

The project ID for your search project. Obtain this from your console dashboard or from the URL of a project configuration page.

Optional Parameters

consumerIdstring

Unique identifier for the user. Used for authenticated search requests and maintaining user context across sessions. Must be provided along with hmacSignature for verified consumers.

hmacSignaturestring

HMAC signature to verify the identity of the consumer. Required when consumerId is provided. Should be generated in the backend using the consumer ID and your project's search API key.

Horizon-Specific Parameters

variant'icon' | 'bar'

Display variant for the search widget. 'icon' shows a compact search button, 'bar' shows a collapsed search bar.

collapsedBarWidthstring

Width of the collapsed search bar when using 'bar' variant. Default is '200px'. Only applies to bar variant.

Optional Callback Functions

These are primarily required for the Beacon template, but can be used for the Horizon template if needed as well.

onSearchResults(results: any[]) => void

Callback function that receives search results. Use this to handle search results in your application logic.

onSearchStart() => void

Callback function triggered when a search begins. Use this for loading states or analytics tracking.

Parameter Notes

• For authenticated search requests, provide both consumerId and hmacSignature.
• If the consumerId and hmacSignature are not provided, cookies are used to create a temporary anonymous consumerId.
• The HMAC signature is needed to verify the identity of the consumer. It should be generated in the backend by passing the consumer ID and your project's search API key to the API route /hmacSignature.
• Both search templates support keyword-based and AI-powered hybrid search modes that users can toggle between.

Usage Guide

Using SearchTemplateBeacon

Import the component and use it for inline search with callback handling:

import '@atri-ai/templates/styles.css';
import { SearchTemplateBeacon } from '@atri-ai/templates';

function SearchPage() {
  const handleSearchResults = (results) => {
    console.log('Search results:', results);
    // Process and display results in your application
  };

  const handleSearchStart = () => {
    console.log('Search started');
    // Show loading state or analytics tracking
  };

  return (
    <div>
      {/* Your existing app content */}
      
      {/* Beacon template for inline search */}
      <SearchTemplateBeacon 
        projectId="your-project-id"
        consumerId="user_12345"
        hmacSignature="hmac-signature-for-the-consumer-id"
        onSearchResults={handleSearchResults}
        onSearchStart={handleSearchStart}
      />
    </div>
  );
}

Using SearchTemplateHorizon

For modal-based search experiences with flexible display variants:

import '@atri-ai/templates/styles.css';
import { SearchTemplateHorizon } from '@atri-ai/templates';

function App() {
  return (
    <div>
      {/* Your existing app content */}
      
      {/* Horizon template with bar variant */}
      <SearchTemplateHorizon 
        projectId="your-project-id"
        consumerId="user_12345"
        hmacSignature="hmac-signature-for-the-consumer-id"
        variant="bar"
        collapsedBarWidth="250px"
      />
      
      {/* Or use icon variant for minimal UI */}
      <SearchTemplateHorizon 
        projectId="your-project-id"
        variant="icon"
      />
    </div>
  );
}

Anonymous Usage

For anonymous search sessions without user verification:

// Anonymous search with Beacon template
<SearchTemplateBeacon 
  projectId="your-project-id"
  onSearchResults={(results) => {
    // Handle results without user tracking
    console.log('Anonymous search results:', results);
  }}
/>

// Anonymous search with Horizon template
<SearchTemplateHorizon 
  projectId="your-project-id"
  variant="bar"
/>

Advanced Integration Examples

Integrate search results with your application state:

import { useState } from 'react';
import { SearchTemplateBeacon } from '@atri-ai/templates';

function SearchWithResults() {
  const [searchResults, setSearchResults] = useState([]);
  const [isSearching, setIsSearching] = useState(false);

  const handleSearchStart = () => {
    setIsSearching(true);
    setSearchResults([]);
  };

  const handleSearchResults = (results) => {
    setSearchResults(results);
    setIsSearching(false);
  };

  return (
    <div>
      <SearchTemplateBeacon 
        projectId="your-project-id"
        consumerId="user_12345"
        hmacSignature="hmac-signature"
        onSearchStart={handleSearchStart}
        onSearchResults={handleSearchResults}
      />
      
      {isSearching && (
        <div className="mt-4 text-center">
          <p>Searching...</p>
        </div>
      )}
      
      {searchResults.length > 0 && (
        <div className="mt-6">
          <h3>Search Results ({searchResults.length})</h3>
          <div className="space-y-4">
            {searchResults.map((result, index) => (
              <div key={index} className="p-4 border rounded-lg">
                <h4 className="font-semibold">{result.title}</h4>
                <p className="text-gray-600">{result.snippet}</p>
                {result.url && (
                  <a href={result.url} className="text-blue-600 hover:underline">
                    View Source
                  </a>
                )}
              </div>
            ))}
          </div>
        </div>
      )}
    </div>
  );
}

Security Requirements

• Never expose your search API key in client-side requests. The HMAC signature should be generated in your backend.
• Always generate the HMAC signature server-side using the /hmacSignature API route with your project's search API key.
• The components are fully secure as you only pass the project ID and HMAC signature, not your API keys.

Template Comparison

SearchTemplateBeacon

• Inline search component
• Direct result callbacks
• Full control over result display
• Best for custom search pages
• Requires result handling logic

SearchTemplateHorizon

• Modal-based search overlay
• Built-in result display
• Compact trigger variants
• Best for navigation/header areas
• Self-contained experience

Important Notes

• Always import the CSS styles: @atri-ai/templates/styles.css
• Components are fully responsive and work on mobile devices
• Both templates support keyword-based and AI-powered hybrid search modes
• Search results include automatic debouncing and autocomplete suggestions
• For best practices, provide the consumer ID if you want user-level search analytics and personalization
• Components automatically adapt their theme colors based on your project configuration

React Component Integration