@intent-ai/react

React component for Intent AI - the AI-powered feedback widget that helps you collect and analyze user feedback effortlessly.

Installation

npm install @intent-ai/react
# or
yarn add @intent-ai/react
# or
pnpm add @intent-ai/react

Quick Start (recommended: IntentAIProvider)

Wrap your app with IntentAIProvider — it renders the premium feedback widget natively (no external script), manages the feedback session, handles GDPR consent, and gives you hooks for user identification:

import { IntentAIProvider } from '@intent-ai/react';

export default function App() {
  return (
    <IntentAIProvider
      apiKey="pk_live_your-key"
      user={{ id: 'user-123', email: '[email protected]' }}
      privacyPolicyUrl="https://yoursite.com/privacy"
    >
      <YourApp />
    </IntentAIProvider>
  );
}

That's it — a floating feedback orb appears, and voice/text feedback flows to your Intent AI dashboard with AI transcription and analysis.

Provider props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiKey | string | required | Your product's pk_live_* key | | apiUrl | string | production API | Override for self-hosted | | user | { id?, email?, name? } | — | Identify the current user | | metadata | object | — | Attached to every feedback | | requireConsent | boolean | true | Show a GDPR consent notice before feedback can be given (voice is processed by AI services; keep this on unless you collect consent elsewhere) | | privacyPolicyUrl | string | — | Linked from the consent notice | | widgetConfig | WidgetConfig | — | Widget look & behavior: position, theme (light/dark/auto), primaryColor, accentColor, allowVoice, allowText, maxRecordingDuration | | disableWidget | boolean | false | Context/hooks only, no floating widget | | onFeedbackSubmitted | () => void | — | After a successful submission | | onError | (e: Error) => void | — | On any failure |

Hooks (inside the provider)

import { useIntentAI } from '@intent-ai/react';

function AccountMenu() {
  const { identify, setMetadata, clearUser } = useIntentAI();

  const onLogin = (user) => identify({ id: user.id, email: user.email });
  const onLogout = () => clearUser();
}

Consent & privacy

Voice recordings are personal data. With requireConsent (the default), the widget shows a short notice — disclosing AI processing (OpenAI, Anthropic) and linking your privacy policy — before the user can record or type feedback. Consent is remembered in the browser and recorded server-side per session, as required by the API's consent gate.

Legacy: script-tag wrapper (IntentAIWidget)

IntentAIWidget loads the CDN widget script instead of rendering natively. Prefer IntentAIProvider for React apps.

import { IntentAIWidget } from '@intent-ai/react';

function App() {
  return (
    <div>
      <h1>My App</h1>

      {/* Add the widget - it will appear as a floating button */}
      <IntentAIWidget
        apiKey="your-api-key"
        apiUrl="https://your-api-url.com"
        widgetUrl="https://your-app-url.com/widget/v1.js"
        position="bottom-right"
        theme="dark"
      />
    </div>
  );
}

That's it! The widget will appear as a floating button in the bottom-right corner of your app.

Note: Get your personalized apiKey, apiUrl, and widgetUrl from the Intent AI Setup Page.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiKey | string | required | Your Intent AI API key | | apiUrl | string | required | Your Intent AI API URL | | widgetUrl | string | required | Your widget script URL | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Widget position | | theme | 'light' \| 'dark' | 'light' | Widget theme | | primaryColor | string | '#3B82F6' | Primary color (hex) | | allowVoice | boolean | true | Enable voice feedback | | allowText | boolean | true | Enable text feedback | | allowScreenshot | boolean | true | Enable screenshot capture | | customMetadata | object | {} | Custom data to attach to feedback | | user | object | undefined | User information |

Identifying Users

Track feedback by user:

<IntentAIWidget
  apiKey="your-api-key"
  apiUrl="https://your-api-url.com"
  widgetUrl="https://your-app-url.com/widget/v1.js"
  user={{
    id: 'user-123',
    email: '[email protected]',
    name: 'John Doe'
  }}
/>

Custom Metadata

Attach custom data to feedback submissions:

<IntentAIWidget
  apiKey="your-api-key"
  apiUrl="https://your-api-url.com"
  widgetUrl="https://your-app-url.com/widget/v1.js"
  customMetadata={{
    page: 'checkout',
    planType: 'premium',
    version: '2.0.0'
  }}
/>

Programmatic Control

Use the useIntentAI hook to control the widget:

import { IntentAIWidget, useIntentAI } from '@intent-ai/react';

function App() {
  const { open, close, identify, setMetadata } = useIntentAI();

  const handleLogin = (user) => {
    identify({
      id: user.id,
      email: user.email,
      name: user.name
    });
  };

  return (
    <div>
      <IntentAIWidget
        apiKey="your-api-key"
        apiUrl="https://your-api-url.com"
        widgetUrl="https://your-app-url.com/widget/v1.js"
      />

      {/* Custom feedback button */}
      <button onClick={open}>
        Give Feedback
      </button>
    </div>
  );
}

Next.js App Router

The component is marked with 'use client' and works with Next.js App Router:

// app/layout.tsx
import { IntentAIWidget } from '@intent-ai/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <IntentAIWidget
          apiKey={process.env.NEXT_PUBLIC_INTENT_AI_KEY!}
          apiUrl={process.env.NEXT_PUBLIC_INTENT_AI_API_URL!}
          widgetUrl={process.env.NEXT_PUBLIC_INTENT_AI_WIDGET_URL!}
        />
      </body>
    </html>
  );
}

Add these to your .env.local:

NEXT_PUBLIC_INTENT_AI_KEY=your-api-key
NEXT_PUBLIC_INTENT_AI_API_URL=https://your-api-url.com
NEXT_PUBLIC_INTENT_AI_WIDGET_URL=https://your-app-url.com/widget/v1.js

Next.js Pages Router

// pages/_app.tsx
import { IntentAIWidget } from '@intent-ai/react';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <IntentAIWidget
        apiKey={process.env.NEXT_PUBLIC_INTENT_AI_KEY!}
        apiUrl={process.env.NEXT_PUBLIC_INTENT_AI_API_URL!}
        widgetUrl={process.env.NEXT_PUBLIC_INTENT_AI_WIDGET_URL!}
      />
    </>
  );
}

Vite / Create React App

// src/App.tsx or src/main.tsx
import { IntentAIWidget } from '@intent-ai/react';

function App() {
  return (
    <div>
      <YourApp />
      <IntentAIWidget
        apiKey={import.meta.env.VITE_INTENT_AI_KEY}
        apiUrl={import.meta.env.VITE_INTENT_AI_API_URL}
        widgetUrl={import.meta.env.VITE_INTENT_AI_WIDGET_URL}
      />
    </div>
  );
}

Add these to your .env:

VITE_INTENT_AI_KEY=your-api-key
VITE_INTENT_AI_API_URL=https://your-api-url.com
VITE_INTENT_AI_WIDGET_URL=https://your-app-url.com/widget/v1.js

Event Callbacks

<IntentAIWidget
  apiKey="your-api-key"
  apiUrl="https://your-api-url.com"
  widgetUrl="https://your-app-url.com/widget/v1.js"
  onOpen={() => console.log('Widget opened')}
  onClose={() => console.log('Widget closed')}
  onFeedbackSubmitted={() => console.log('Feedback submitted!')}
  onError={(error) => console.error('Widget error:', error)}
/>

TypeScript

Full TypeScript support included:

import { IntentAIWidget, IntentAIProps, IntentAIUser } from '@intent-ai/react';

const user: IntentAIUser = {
  id: '123',
  email: '[email protected]',
  name: 'John'
};

const config: IntentAIProps = {
  apiKey: 'your-api-key',
  user,
  theme: 'dark'
};

Getting Your API Key

1. Sign up at Intent AI Dashboard
2. Create an organization and product
3. Copy your API key from the setup page

Support

• Documentation: docs.intent-ai.com
• Issues: GitHub Issues

License

MIT