@oops/react-widget

A React widget for collecting user feedback with screenshots, browser information, and seamless integration into any React application.

📖 Complete Documentation

View Live Demo | API Examples

Designed with Johnny Ive's principles in mind: Simple. Elegant. Functional.

Installation

npm install @oops/react-widget

Quick Start

1. Basic Floating Widget

import { FeedbackWidget } from '@oops/react-widget';

function App() {
  return (
    <div>
      <h1>My App</h1>
      <FeedbackWidget
        projectId="proj_abc123"
        publicKey="pk_live_xyz789"
        position="bottom-right"
        theme="auto"  // Auto-detect light/dark mode
      />
    </div>
  );
}

2. Custom Trigger Button

<FeedbackWidget
  projectId="proj_abc123"
  publicKey="pk_live_xyz789"
  position="none"
  renderTrigger={({ onClick, isLoading }) => (
    <button onClick={onClick} disabled={isLoading}>
      🐛 Report Issue
    </button>
  )}
/>

3. Controlled Modal

import { FeedbackModal } from '@oops/react-widget';

function MyComponent() {
  const [showFeedback, setShowFeedback] = useState(false);

  return (
    <div>
      <button onClick={() => setShowFeedback(true)}>
        Give Feedback
      </button>

      <FeedbackModal
        projectId="proj_abc123"
        publicKey="pk_live_xyz789"
        isOpen={showFeedback}
        onClose={() => setShowFeedback(false)}
      />
    </div>
  );
}

4. Hook Pattern (Maximum Flexibility)

import { FeedbackProvider, useFeedback } from '@oops/react-widget';

// App root
function App() {
  return (
    <FeedbackProvider projectId="proj_abc123" publicKey="pk_live_xyz789">
      <MyApp />
    </FeedbackProvider>
  );
}

// Anywhere in your component tree
function CustomFeedbackComponent() {
  const { submitFeedback, isSubmitting, error } = useFeedback();

  const handleSubmit = async () => {
    await submitFeedback({
      text: "Custom feedback",
      userInfo: { email: "[email protected]" }
    });
  };

  return (
    <button onClick={handleSubmit} disabled={isSubmitting}>
      {isSubmitting ? "Sending..." : "Send Feedback"}
    </button>
  );
}

Theme Configuration

The widget supports automatic dark mode detection and manual theme control with a beautiful orange accent color (#FF6B4A).

Theme Options

// Auto-detect system theme (default)
<FeedbackWidget
  projectId="proj_abc123"
  publicKey="pk_live_xyz789"
  theme="auto"  // Follows user's system preference
/>

// Force light mode
<FeedbackWidget
  projectId="proj_abc123"
  publicKey="pk_live_xyz789"
  theme="light"
/>

// Force dark mode
<FeedbackWidget
  projectId="proj_abc123"
  publicKey="pk_live_xyz789"
  theme="dark"
/>

Visual Design

Light Mode:

• Frosted white glass backgrounds with subtle transparency
• Dark text (#1d1d1f) for optimal readability
• Orange accents (#FF6B4A) for interactive elements
• Soft shadows for depth

Dark Mode:

• Frosted dark glass backgrounds (rgba(30-50, 30-50, 30-50))
• White text (#ffffff) with high contrast
• Same vibrant orange accents (#FF6B4A)
• Deeper shadows for dramatic depth
• Your logo remains in original colors

Orange Accent Color (#FF6B4A) Used For:

• Submit button background and hover states
• Input/textarea focus borders and glow
• Checkbox checked state
• All interactive states and highlights

Theme with Modal

<FeedbackModal
  projectId="proj_abc123"
  publicKey="pk_live_xyz789"
  isOpen={showFeedback}
  onClose={() => setShowFeedback(false)}
  theme="auto"  // Auto-detect or use 'light' / 'dark'
/>

The theme automatically applies to all components:

• Floating feedback button
• Modal container and overlays
• Category selection cards
• Form inputs, textareas, and buttons
• Checkboxes and interactive elements

Props

FeedbackWidget

| Prop | Type | Default | Description | |------|------|---------|-------------| | projectId | string | - | Your Oops! project ID | | publicKey | string | - | Your public API key (pk_live_* or pk_test_*) | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' \| 'none' | 'bottom-right' | Widget position | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | Color theme - 'auto' detects system preference | | enableScreenshot | boolean | true | Enable screenshot capture | | enableBrowserInfo | boolean | true | Include browser information | | userInfo | object | - | Pre-fill user information | | onSubmit | function | - | Callback when feedback is submitted | | onError | function | - | Callback when an error occurs |

Features

• 📸 Screenshot Capture - Let users capture and include screenshots
• 🌐 Browser Info - Automatically collect browser and viewport information
• 🎨 Themeable - Light, dark, and auto themes with beautiful orange accents
• 🌓 Auto Dark Mode - Automatically detects and follows system theme preference
• 📱 Mobile Friendly - Responsive design for all devices
• 🔒 Secure - Domain validation and API key security
• ⚡ Lightweight - Minimal bundle size with tree-shaking support
• 🎯 Flexible - Multiple integration patterns
• ✨ Jony Ive Inspired - Frosted glass effects, refined shadows, and minimal design

Requirements

• React 16.8+ (hooks support)
• Modern browser with ES6+ support

License

MIT