Gentiq React SDK

The core React library for building premium, production-ready AI chatbot interfaces.

gentiq provides a set of highly modular conversational components built on top of Vercel AI SDK and Vite. It offers both a complete, drop-in UI and granular "slots" for building highly customized conversational flows.

📦 Installation

npm install gentiq
# or
pnpm add gentiq

🚀 Quick Start

import { GentiqProvider, ChatUI, RequireAuth, UserLoginPage } from 'gentiq';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import 'gentiq/style.css';

export default function App() {
  return (
    <GentiqProvider
      api={{ authAdapter: LocalStorageAuthAdapter }}
      app={{ version: '1.2.3' }}
    >
      <BrowserRouter>
        <Routes>
          <Route path="/login" element={<UserLoginPage />} />
          <Route path="/*" element={
            <RequireAuth>
               <ChatUI />
            </RequireAuth>
          } />
        </Routes>
      </BrowserRouter>
    </GentiqProvider>
  );
}

If you already expose your app version at build time, pass that value here so Gentiq reuses the same source of truth.

🎨 Extreme Customization (Slots)

Gentiq is designed to be "hacked" at any level. Using the components prop, you can surgically replace internal components with your own implementation.

UI Slot Overrides

Replace message bubbles, input areas, or the entire message list without forking the library.

import { GentiqComponents, TextPartProps } from 'gentiq';

const MyBrandedTextBubble = ({ part, message }: TextPartProps) => (
  <div className={`p-4 rounded-3xl ${message.role === 'user' ? 'bg-blue-600 text-white' : 'bg-gray-100'}`}>
    <p>{part.text}</p>
    <span className="text-[10px] opacity-50">{new Date(message.createdAt).toLocaleTimeString()}</span>
  </div>
);

const components: GentiqComponents = {
  TextPart: MyBrandedTextBubble,
  WelcomeScreen: () => <div className="p-20 text-center"><h1>Welcome to My AI</h1></div>,
  // Override the input area entirely
  PromptInput: ({ onSend, status }) => (
    <input 
      disabled={status === 'streaming'} 
      onKeyDown={(e) => e.key === 'Enter' && onSend(e.currentTarget.value)} 
    />
  )
};

<ChatUI components={components} />

Markdown & Tool Customization

You can even intercept markdown rendering or provide custom dashboards for specific AI tool calls.

const components: GentiqComponents = {
  // Custom markdown component overrides (passed to react-markdown)
  textComponents: {
    code: ({ children }) => <pre className="my-custom-code">{children}</pre>,
  },
  // Custom UI for specific tools
  toolComponents: {
    get_weather: ({ part }) => (
      <div className="weather-card">
        <h3>{part.result.city}</h3>
        <p>{part.result.temperature}°C</p>
      </div>
    ),
  },
  // Inject remark/rehype plugins
  remarkPlugins: [remarkGfm],
};

References for Text, Tools, and Custom Cards

Gentiq includes a built-in reference UX similar to modern AI chat apps. Users can select text in previous messages, click the reference action, and Gentiq will add a compact quote chip to the composer. When the message is sent, the referenced context is sent to the backend/model and shown as a clickable badge in the chat.

For normal text messages, this works automatically. For custom cards, use Referenceable or useChatReferences so Gentiq knows exactly what should be referenced and how it should appear to the user.

Reference a custom card

Use Referenceable when your component has a clear card-like boundary. Gentiq will add a hover reference action, register the source for click-to-highlight, and send the structured reference with the next user message.

import { Referenceable } from 'gentiq';

function CarCard({ car }) {
  return (
    <Referenceable
      reference={{
        kind: 'car',
        sourceId: `car-${car.id}`,
        label: 'Car',
        excerpt: `${car.year} ${car.make} ${car.model} · ${car.price}`,
        data: {
          carId: car.id,
          make: car.make,
          model: car.model,
          year: car.year,
          price: car.price,
        },
      }}
    >
      <div className="car-card">
        <CarImageCarousel images={car.images} />
        <h3>{car.year} {car.make} {car.model}</h3>
        <p>{car.price}</p>
      </div>
    </Referenceable>
  );
}

excerpt is the human-readable text shown in the composer chip and reference badge. data is optional structured context, useful for IDs or machine-readable values like { carId }.

Use your own reference button

If you do not want the built-in hover action, call addReference yourself. Keep the sourceId on the element you want highlighted later.

import { useChatReferences } from 'gentiq';

function CarCard({ car }) {
  const { addReference } = useChatReferences();

  const reference = {
    kind: 'car',
    sourceId: `car-${car.id}`,
    label: 'Car',
    excerpt: `${car.year} ${car.make} ${car.model} · ${car.price}`,
    data: { carId: car.id },
  };

  return (
    <div data-gentiq-reference-source-id={reference.sourceId}>
      <CarImageCarousel images={car.images} />
      <h3>{car.year} {car.make} {car.model}</h3>

      <button type="button" onClick={() => addReference(reference)}>
        Reference this car
      </button>
    </div>
  );
}

Customize tool/card reference text

For tool-rendered cards, use referenceAdapters to control what appears in the composer and sent reference context. This avoids showing raw JSON to users.

const components: GentiqComponents = {
  toolComponents: {
    get_weather: WeatherCard,
  },
  referenceAdapters: {
    get_weather: ({ part }) => ({
      label: 'Weather',
      excerpt: `Weather: ${part.output.city}: ${part.output.condition}`,
      data: {
        city: part.output.city,
        condition: part.output.condition,
      },
    }),
  },
};

<ChatUI components={components} />

For markdown patterns like [CarCard](car_id), render your CarCard from the markdown override, fetch the car data as usual, and wrap the rendered card with Referenceable as shown above.

⚓ Headless Mode

If you need complete control over the UI, use the useGentiqChat hook. It handles all the complex synchronization with the Vercel AI SDK and Gentiq's persistence backend while leaving the rendering to you.

import { useGentiqChat } from 'gentiq';

export const CustomChat = () => {
  const { messages, input, setInput, append, isLoading } = useGentiqChat();

  return (
    <div>
      {messages.map(m => <div key={m.id}>{m.content}</div>)}
      <input value={input} onChange={e => setInput(e.target.value)} />
      <button onClick={() => append({ role: 'user', content: input })}>Send</button>
    </div>
  );
};

🔐 Admin & Shared Views

Gentiq includes production-grade views for administration and public sharing.

• <AdminPanel />: A complete dashboard customizable with extraPages.
• <SharedChatView />: A read-only view for public conversation links.

<Route path="/admin/*" element={<AdminPanel extraPages={[{ path: 'metrics', label: 'Metrics', element: <MyMetrics /> }]} />} />
<Route path="/shared/:shareId" element={<SharedChatView />} />

🌍 Advanced Theming & i18n

Support multiple languages (including RTL) and customize your brand's unique look.

<GentiqProvider
  theme={{
    defaultTheme: 'system',
    accent: '#6366f1',
    radius: 20,
    typography: {
      fontFamily: {
        en: 'Inter, sans-serif',
        fa: 'Vazirmatn, sans-serif' // Built-in RTL support
      }
    }
  }}
  i18n={{
    resources: {
      en: { chat: { input_placeholder: "Ask me anything..." } },
      fa: { chat: { input_placeholder: "هرچیزی میخواهی بپرس..." } }
    }
  }}
>
  <ChatUI />
</GentiqProvider>

defaultTheme accepts system, light, or dark. Appearance preferences are resolved in this order: the user's saved preference, the defaults configured in the admin settings page, the theme values passed to GentiqProvider, and finally Gentiq's built-in defaults.

👥 Custom User Metadata Fields

Easily extend user profiles and signup forms with your own fields. Gentiq handles the state, validation, and conditional visibility (branching logic) automatically.

<GentiqProvider
  app={{
    userMetadataFields: [
      {
        key: 'organization',
        label: 'settings:profile.organization',
        type: 'text',
        placeholder: 'Enter your company name',
        showInSignup: true,
        showInProfile: true,
      },
      {
        key: 'role',
        label: 'settings:profile.role',
        type: 'select',
        options: [
          { label: 'Developer', value: 'dev' },
          { label: 'Manager', value: 'manager' },
        ],
        // Field only shown if organization is provided
        condition: { field: 'organization', operator: 'not_equals', value: '' },
        showInSignup: true,
        showInProfile: true,
      }
    ]
  }}
>
  <ChatUI />
</GentiqProvider>

Personalized Greetings

Use a functional greeting to personalize the built-in welcome screen. Gentiq loads and caches the authenticated profile for you:

<GentiqProvider
  welcome={{
    greeting: ({ firstName, t }) =>
      t(firstName ? 'chat:welcome.named' : 'chat:welcome.default', {
        firstName,
      }),
  }}
  i18n={{
    resources: {
      en: {
        chat: {
          welcome: {
            default: 'How can I help you today?',
            named: 'Hi {{firstName}}, how can I help you today?',
          },
        },
      },
    },
  }}
>
  <ChatUI />
</GentiqProvider>

For custom screens or other components, use the same profile data directly:

import { useGentiqUser } from 'gentiq';

function MyWelcomeScreen() {
  const { user, firstName, isLoading, error } = useGentiqUser();

  if (isLoading) return null;
  if (error) return <h1>Welcome!</h1>;

  return <h1>Welcome, {firstName || user?.phone}!</h1>;
}

Typing-Effect Subtitle

Instead of the static subtitle and clickable suggestion bubbles, you can show a rotating subtitle that types itself out, cycling through any number of messages. Set welcome.typingPrompts to a string array, or to a function that receives the authenticated user so the messages can be conditioned on user info. When set, this replaces both the static subtitle and the prompts suggestion bubbles.

// Static list
<GentiqProvider
  welcome={{
    greeting: 'Welcome back',
    typingPrompts: [
      'Ask me anything…',
      'Summarize a document',
      'Draft an email',
    ],
  }}
>
  <ChatUI />
</GentiqProvider>

// Conditioned on the authenticated user
<GentiqProvider
  welcome={{
    greeting: 'Welcome back',
    typingPrompts: ({ firstName }) =>
      firstName
        ? [`Ask me anything, ${firstName}…`, 'Summarize a document', 'Draft an email']
        : ['Ask me anything…', 'Summarize a document', 'Draft an email'],
  }}
>
  <ChatUI />
</GentiqProvider>

The function receives the same context as the personalized greeting ({ user, firstName, isLoading, t }). The typewriter respects the user's prefers-reduced-motion setting, swapping whole messages instead of animating each character when reduced motion is requested.

📄 License

Gentiq is open-source software licensed under the Apache 2.0 License.