🎯 Feedbacker Core

A zero-configuration React feedback system that enables component-level feedback capture with automatic screenshot functionality.

Features

✨ Zero Configuration - Just wrap your app and start collecting feedback
🎯 Component-Level - Users can select specific React components for feedback
📱 Mobile Optimized - Touch and drag interactions with haptic feedback
📸 Screenshot Capture - Pluggable capture libraries (html2canvas, SnapDOM)
💾 Local Persistence - Feedback stored locally with export options
🚀 Performance First - < 50KB bundle with lazy loading and optimizations
🎨 Customizable - Theming and positioning options
🔧 TypeScript Ready - Full TypeScript support with comprehensive types

Quick Start

Installation

npm install feedbacker-react

Basic Usage

import React from 'react';
import { FeedbackProvider } from 'feedbacker-react';
// CSS is automatically injected - no manual import needed!

function App() {
  return (
    <FeedbackProvider>
      <YourApp />
    </FeedbackProvider>
  );
}

That's it! Users can now:

• Hover over components to highlight them (desktop)
• Touch and drag to select components (mobile)
• Click/tap to provide feedback with screenshots
• Press Esc to exit feedback mode

Configuration Options

<FeedbackProvider
  position="bottom-right"        // FAB position
  primaryColor="#3b82f6"        // Theme color
  enabled={true}                // Enable/disable system
  storageKey="my-app-feedback"  // LocalStorage key
  onFeedbackSubmit={(feedback) => {
    console.log('New feedback:', feedback);
    // Send to your backend
  }}
>
  <YourApp />
</FeedbackProvider>

Props API

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' | 'bottom-right' | FAB position | | primaryColor | string | '#3b82f6' | Primary theme color | | enabled | boolean | true | Enable/disable feedback system | | storageKey | string | 'feedbacker' | LocalStorage key prefix | | captureLibrary | 'html2canvas' \| 'snapdom' | 'html2canvas' | Screenshot capture library | | onFeedbackSubmit | (feedback: Feedback) => void | - | Callback when feedback is submitted |

Advanced Usage

Using Hooks

import { useFeedback, useFeedbackStorage } from 'feedbacker-react';

function MyComponent() {
  const { feedbacks, addFeedback, exportFeedback } = useFeedback();
  const { isLoading, error } = useFeedbackStorage();

  const handleExport = async () => {
    await exportFeedback({ 
      format: 'zip', 
      includeImages: true 
    });
  };

  return (
    <div>
      <p>Total feedback: {feedbacks.length}</p>
      <button onClick={handleExport}>Export Feedback</button>
    </div>
  );
}

Screenshot Capture Libraries

Feedbacker supports multiple screenshot libraries through a pluggable adapter system. Install your preferred library:

# Option 1: SnapDOM (Recommended - faster, more accurate)
npm install @zumer/snapdom

# Option 2: html2canvas (Default - better compatibility)
npm install html2canvas

Then configure in your provider:

// Use SnapDOM for better performance
<FeedbackProvider captureLibrary="snapdom">
  <YourApp />
</FeedbackProvider>

// Or use html2canvas (default)
<FeedbackProvider captureLibrary="html2canvas">
  <YourApp />
</FeedbackProvider>

Note: Libraries are loaded as peer dependencies. If not installed via npm, they will automatically load from CDN as a fallback.

See CAPTURE_LIBRARIES.md for detailed documentation and custom adapter implementation.

Event System

import { useFeedbackEvent } from 'feedbacker-react';

function CustomComponent() {
  const { on, emit } = useFeedbackEvent();

  useEffect(() => {
    // Listen for feedback events
    const unsubscribe = on('feedback:submit', (feedback) => {
      console.log('Feedback submitted:', feedback);
    });

    return unsubscribe;
  }, [on]);

  const triggerFeedback = () => {
    emit('modal:open', { componentInfo });
  };

  return <button onClick={triggerFeedback}>Give Feedback</button>;
}

Data Types

Feedback Object

interface Feedback {
  id: string;
  componentName: string;
  componentPath: string[];
  comment: string;
  screenshot?: string;
  url: string;
  timestamp: string;
  browserInfo: BrowserInfo;
  metadata?: Record<string, any>;
}

Export Options

interface ExportOptions {
  format: 'markdown' | 'zip';
  includeImages: boolean;
  includeMetadata: boolean;
}

Component Detection

Feedbacker automatically detects React components using multiple strategies:

1. React DevTools Integration - Most accurate, works with development builds
2. Fiber Tree Inspection - Direct React internals access
3. DOM Heuristics - Fallback method using DOM analysis
4. Unknown Component - Final fallback for unidentifiable elements

Performance Optimizations

• RequestIdleCallback - Component detection runs during browser idle time
• Debounced Interactions - Mouse/touch events are throttled
• React.memo - Components are memoized to prevent unnecessary re-renders
• Lazy Loading - html2canvas is loaded on-demand
• Zero Impact When Inactive - No performance overhead when not in use

Mobile Support

Touch Interactions

• Touch and Drag - Select components by dragging
• Haptic Feedback - Vibration feedback on compatible devices
• Responsive UI - Mobile-optimized interface

Viewport Configuration

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

Browser Support

• Modern Browsers - Chrome 60+, Firefox 60+, Safari 12+, Edge 79+
• ES6+ Features - Uses modern JavaScript features
• React 18+ - Requires React 18 or higher
• Optional Features:
  • Screenshot capture requires browser canvas support
  • Haptic feedback requires Vibration API

Storage and Export

Local Storage

• Feedback is automatically saved to localStorage
• 5MB storage limit with cleanup
• Data migration for version updates
• Corruption recovery with fallback

Export Formats

Markdown Export

await exportFeedback({ 
  format: 'markdown',
  includeImages: false,
  includeMetadata: true 
});

ZIP Export (with Images)

await exportFeedback({ 
  format: 'zip',
  includeImages: true,
  includeMetadata: true 
});

Styling and Theming

CSS Variables

:root {
  --fb-primary: #3b82f6;
  --fb-background: #ffffff;
  --fb-text: #1f2937;
  --fb-border: #e5e7eb;
  --fb-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}

Custom Styles

.feedbacker-fab {
  /* Custom FAB styles */
}

.feedbacker-modal {
  /* Custom modal styles */
}

.feedbacker-overlay {
  /* Custom overlay styles */
}

Demo

Run the demo locally:

cd packages/feedbacker/demo
open index.html

The demo showcases:

• Various component types (buttons, cards, forms, tables)
• Mobile and desktop interactions
• Screenshot capture functionality
• Export capabilities
• Real-time feedback collection

Bundle Analysis

| Format | Size (Gzipped) | Description | |--------|----------------|-------------| | ESM | ~15KB | Modern bundle for ES6+ environments | | CJS | ~18KB | CommonJS for Node.js compatibility | | UMD | ~25KB | Universal bundle with dependencies |

Dependencies

• Peer Dependencies: React 18+, ReactDOM 18+
• Optional Dependencies: html2canvas (lazy loaded)
• Zero Runtime Dependencies in core bundle

Troubleshooting

Common Issues

Screenshot not capturing:

• Ensure user has granted permission
• Check for CORS issues with external images
• Verify html2canvas compatibility

Component detection not working:

• Enable React DevTools for best results
• Ensure components have displayName or are named functions
• Check browser console for detection errors

Storage quota exceeded:

• Feedback system automatically cleans up old data
• Use export functionality to backup data
• Consider implementing server-side storage

Debug Mode

<FeedbackProvider 
  onFeedbackSubmit={(feedback) => {
    console.log('[Debug] Feedback:', feedback);
  }}
>
  <App />
</FeedbackProvider>

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see LICENSE file for details.

Support

• 📚 Documentation
• 🐛 Issues
• 💬 Discussions
• 📧 Support Email

Made with ❤️ by the Feedbacker team