forms-agent-lib

v1.0.7

Published

4 months ago

Voice-powered form filling library for Next.js and React applications

0High
0Medium
0Low

bukareszt

forms voice speech-to-text form-filling nextjs react b2b conversion ai whisper

Forms Agent Library 🎤

Transform any form into a voice-enabled powerhouse in minutes.

Forms Agent is a drop-in JavaScript library that adds voice-powered form filling to your Next.js or React applications. Perfect for B2B SaaS companies looking to improve form conversion rates and user experience.

✨ Features

🎯 Zero Configuration - Works with any HTML form out of the box
🎤 Voice-Powered - Users can fill forms by speaking naturally
🎨 Beautiful UI - Subtle microphone icon and grayed fields indicate voice capability
⚡ Fast Integration - Add to your Next.js app in under 5 minutes
🔒 Secure - API key authentication and encrypted communication
📱 Responsive - Works on desktop and mobile devices
🌐 Framework Agnostic - Works with React, Next.js, Vue, or vanilla HTML

🚀 Quick Start (Next.js)

1. Install the package

npm install forms-agent-lib
# or
yarn add forms-agent-lib

2. Run the setup script

npx forms-agent-lib setup

This will:

Copy forms-agent.js to your public/ folder
Create .env.local with configuration variables
Show you how to integrate it

3. Add to your layout

// app/layout.tsx
import { FormsAgentProvider } from 'forms-agent-lib/nextjs';
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <FormsAgentProvider
          apiUrl={process.env.NEXT_PUBLIC_FORMS_AGENT_API_URL!}
          apiKey={process.env.NEXT_PUBLIC_FORMS_AGENT_API_KEY!}
        >
          {children}
        </FormsAgentProvider>
        
        <Script src="/forms-agent.js" strategy="afterInteractive" />
      </body>
    </html>
  );
}

4. Update your environment variables

# .env.local
NEXT_PUBLIC_FORMS_AGENT_API_URL=https://your-api.com
NEXT_PUBLIC_FORMS_AGENT_API_KEY=your-api-key

That's it! 🎉 All forms in your app now have voice capabilities.

📖 Usage Examples

Basic Contact Form

// app/contact/page.tsx
export default function ContactPage() {
  return (
    <form>
      <input type="text" name="name" placeholder="Your name" />
      <input type="email" name="email" placeholder="Your email" />
      <textarea name="message" placeholder="Your message" />
      <button type="submit">Send</button>
    </form>
  );
}

The form automatically gets:

✨ Slightly grayed fields to indicate voice capability
🎤 A microphone icon in the top-right corner
🎯 One-click voice recording

Advanced Configuration

import { FormsAgentProvider } from 'forms-agent-lib/nextjs';

<FormsAgentProvider
  apiUrl={process.env.NEXT_PUBLIC_FORMS_AGENT_API_URL!}
  apiKey={process.env.NEXT_PUBLIC_FORMS_AGENT_API_KEY!}
  showWelcomePopup={true}
  micIconPosition="top-center"
  theme={{
    micBackground: '#10b981',
    micHover: '#059669',
    fieldGray: 'rgba(0, 0, 0, 0.03)'
  }}
>
  {children}
</FormsAgentProvider>

Using the Hook (Advanced)

'use client';

import { useFormsAgent } from 'forms-agent-lib/nextjs';

export function MyForm() {
  useFormsAgent({
    apiUrl: process.env.NEXT_PUBLIC_FORMS_AGENT_API_URL!,
    apiKey: process.env.NEXT_PUBLIC_FORMS_AGENT_API_KEY!,
    showWelcomePopup: false,
    micIconPosition: 'top-left'
  });

  return (
    <form>
      {/* Your form fields */}
    </form>
  );
}

🎨 Customization

Microphone Icon Position

micIconPosition="top-right"  // default
micIconPosition="top-left"
micIconPosition="top-center"

Theme Customization

theme={{
  fieldGray: 'rgba(0, 0, 0, 0.03)',      // Background color for form fields
  micBackground: '#10b981',               // Microphone button color
  micHover: '#059669',                    // Hover color
  recording: '#ef4444',                   // Recording state color
  processing: '#f59e0b'                   // Processing state color
}}

Disable Welcome Popup

showWelcomePopup={false}

Disable Auto-Gray Fields

autoGrayFields={false}

🔧 Vanilla JavaScript / HTML

If you're not using React or Next.js:

<!DOCTYPE html>
<html>
<head>
  <title>My Form</title>
</head>
<body>
  <form>
    <input type="text" name="name" placeholder="Name" />
    <input type="email" name="email" placeholder="Email" />
    <button type="submit">Submit</button>
  </form>

  <!-- Load Forms Agent -->
  <script src="https://unpkg.com/forms-agent-lib@3/dist/forms-agent.js"></script>
  <script>
    FormsAgent.init({
      apiUrl: 'https://your-api.com',
      apiKey: 'your-api-key'
    });
  </script>
</body>
</html>

🏢 For B2B Customers

Why Forms Agent?

Increase Conversion Rates - Voice input is 3x faster than typing
Improve Accessibility - Help users with disabilities or mobile users
Stand Out - Modern, innovative UX that competitors don't have
Easy Integration - Add to existing forms in minutes, no redesign needed

Enterprise Features

🔐 API Key Authentication - Secure access control
📊 Analytics Ready - Track voice vs. manual form fills
🎨 White Label - Customize colors to match your brand
🌍 Multi-language - Supports 50+ languages via Whisper AI
⚡ High Performance - Optimized for speed and reliability
📱 Mobile Optimized - Works seamlessly on all devices

Pricing Models

This library works with your own backend API. You have full control over:

Usage limits
User authentication
Data storage
API costs

🔑 API Configuration

Environment Variables

NEXT_PUBLIC_FORMS_AGENT_API_URL=https://your-api.com
NEXT_PUBLIC_FORMS_AGENT_API_KEY=your-secret-key

API Requirements

Your backend API should accept:

Endpoint: POST /api/process
Headers: X-API-Key: your-api-key
Body: FormData with audio (WAV file) and html (form HTML)
Response: JSON with field_values array

Example response:

{
  "type": "success",
  "transcript": "My name is John Doe...",
  "field_values": [
    {
      "field_name": "name",
      "field_label": "Name",
      "value": "John Doe"
    },
    {
      "field_name": "email",
      "field_label": "Email",
      "value": "[email protected]"
    }
  ]
}

🛠️ API Methods

FormsAgent.init(config)

Initialize Forms Agent on the page.

FormsAgent.init({
  apiUrl: 'https://your-api.com',
  apiKey: 'your-api-key',
  showWelcomePopup: true,
  micIconPosition: 'top-right'
});

FormsAgent.show()

Show all voice controls (if previously hidden).

FormsAgent.show();

FormsAgent.hide()

Hide all voice controls.

FormsAgent.hide();

FormsAgent.destroy()

Remove Forms Agent and clean up all enhancements.

FormsAgent.destroy();

FormsAgent.updateConfig(config)

Update configuration after initialization.

FormsAgent.updateConfig({
  micIconPosition: 'top-left'
});

📱 Browser Support

✅ Chrome 60+
✅ Firefox 55+
✅ Safari 11+
✅ Edge 79+
✅ Mobile Chrome (Android)
✅ Mobile Safari (iOS)

Requires browser support for:

MediaRecorder API
getUserMedia API
ES6+

🤝 Support

📄 License

MIT License - see LICENSE file for details.

🌟 Show Your Support

If you like this project, please give it a ⭐️ on GitHub!

Made with ❤️ for developers who want to build better forms