Skip to main content

React

Overview​

The ai12z Search/Ask React Control allows seamless integration of AI-powered search capabilities into your React pages. This control is loaded from a Content Delivery Network (CDN) and can be customized through a variety of properties. See Agent Settings API Key to get your API key

Setup

To install from npm

npm install @ai12z/react
npm install ai12z

Next.js Integration​

Because the Stencil React output target uses the Stencil library compiled file to render web components, Next.js applications require an additional initialization step to ensure custom elements are registered before they are rendered.

🛠️ Step 1: Create the ai12z-controls-init.tsx File​

Create a new file named ai12z-controls-init.tsx in your project (e.g., components/ai12z-controls-init.tsx):

"use client"

import { useEffect, useState } from "react"
import { defineCustomElements } from "ai12z/loader"

export default function ai12zControlsInit({
  children,
}: {
  children: React.ReactNode
}): JSX.Element {
  const [isRegistered, setIsRegistered] = useState(false)

  useEffect(() => {
    const registerComponents = async (): Promise<void> => {
      // 1. Perform your registration logic
      defineCustomElements(window)
      // 2. Wait for the browser to acknowledge the definition
      await customElements.whenDefined("ai12z-cta")

      setIsRegistered(true)
    }

    void registerComponents()
  }, [])

  if (!isRegistered) return <>Loading...</>

  return <>{children}</>
}

This component:

  • Calls defineCustomElements(window) to register all ai12z web components from the Stencil loader.
  • Waits for the primary component (ai12z-cta) to be fully defined in the browser before rendering children.
  • Shows a Loading... fallback while registration is in progress.

🛠️ Step 2: Import ai12z-controls-init in layout.tsx​

Wrap your application's children with Ai12zControlsInit in your root layout.tsx file:

import ai12zControlsInit from "@/components/ai12z-controls-init"

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <Ai12zControlsInit>{children}</Ai12zControlsInit>
      </body>
    </html>
  )
}

This ensures all ai12z web components are registered globally before any page renders them.

Search / Ask AI​

  • Include this below command to use the control.
import { Ai12zCta } from '@ai12z/react'
  • Then you can use the element anywhere in your template.
  • The control named as Ai12zCta allows us to show the search results along with the follow up chat conversations and customize our search results.
  • This control is having two tag element which is mentioned below.
<Ai12zCta options={{ allowClose: true }}>
  <privacy></privacy>
  <cta></cta>
</Ai12zCta>
  • (Optional) This tag element allows us to add the privacy policy links.
 <privacy slot="custom-privacy">Privacy Statement
      <a href="https://ai12z.com/privacy-policy/" target="_blank">Click to view</a
    </privacy>
  • (Optional) This tag element allows us to customize our page by adding our own tag elements within this element.
<cta>
    <img src="ai_icon.png" />
</cta>
  • The control contains following properties to customize the page.
PropertyDescriptionExampleDefault
dataKey (Required)API key from your ai12z Agent settingsdataKey="123456"
configId (Optional)Configure the particular botconfigId="123455"
dataMode (Optional)Server to use dev or proddataMode="dev"prod
options (Optional)This property allow us to pass the objects with key value pair to override the value which is set in the config page. options={{allowClose: true}}

Knowledge Box​

  • The second control named as Ai12zKnowledgeBox allows us to send the query programmmatically through javascript and rendering the query results by clicking on the button.

  • Include this below command to use the control.

import { Ai12zKnowledgeBox } from '@ai12z/react'
<Ai12zKnowledgeBox>

</Ai12zKnowledgeBox>

Attributes and Customization​

PropertyDescriptionExampleDefault
dataKey (Required)API key from your ai12z Agent settingsdataKey="123456"
dataMode (Optional)Server to use dev or proddataMode="dev"prod
question (Optional)Sets a pre-loaded question when the component loads Onloadquestion="what does ai12z do"
relavanceScore (Optional)View relavance ScorerelavanceScore="true"false
thumbsUpDown (Optional)Enables thumbs up or down feedbackthumbsUpDown="true"false

Typical Usage Example​

This example demonstrates how to connect a third-party search box with the Ai12zKnowledgeBox component to handle search queries dynamically. When a user enters a query in the search box and presses the search button, the question is programmatically submitted to the Ai12zKnowledgeBox, which then updates to display the relevant results.

Step 1: Set Up the Component​

First, ensure you've imported the Ai12zKnowledgeBox component:

import { Ai12zKnowledgeBox } from '@ai12z/react';

Step 2: Create a Search Box Next, define a search box in your React component where users can input their queries:

import React, { useState } from 'react';

const SearchComponent = () => {
  const [question, setQuestion] = useState('');

  const handleSearch = () => {
    // Assuming `Ai12zKnowledgeBoxRef` is a ref attached to the Ai12zKnowledgeBox component
    Ai12zKnowledgeBoxRef.current.setAttribute('question', question);
  };

  return (
    <div>
      <input
        type="text"
        value={question}
        onChange={(e) => setQuestion(e.target.value)}
        placeholder="Enter your question..."
      />
      <button onClick={handleSearch}>Search</button>
      <Ai12zKnowledgeBox ref={Ai12zKnowledgeBoxRef} dataKey="your-api-key" />
    </div>
  );
};

export default SearchComponent;

Step 3: Connect the Search Box to Ai12zKnowledgeBox​

In this example, when the user types a question and clicks the search button, the handleSearch function updates the question attribute of the Ai12zKnowledgeBox component via a React ref. This causes the component to re-render and display new content based on the updated question.

Ensure that the dataKey is correctly set to your specific API key for the Ai12zKnowledgeBox.

This setup creates a dynamic interaction where the Ai12zKnowledgeBox immediately reflects the user's queries, allowing for a seamless integration of AI-powered search functionality into your application.