🎈 Balloon Feedback React

Interactive balloon pop feedback component for React - collect user feedback with satisfying burst animations!

✨ Features

• 🎈 Interactive balloon animations with Framer Motion
• 💥 Satisfying pop effect with particle burst
• 🔊 Sound effects (with Web Audio API fallback)
• 🎨 Fully customizable colors, labels, and positions
• 📱 Responsive and mobile-friendly
• 🌙 Dark mode support
• 💾 Auto-saves feedback to localStorage
• 🪝 Callback support for analytics integration

📦 Installation

npm install @vedhasagaran/balloon-feedback framer-motion

🚀 Quick Start

import { BalloonFeedback } from '@vedhasagaran/balloon-feedback';

function App() {
  return (
    <BalloonFeedback
      question="Did you like the night mode?"
      onFeedback={(rating, label) => {
        console.log(`User rated: ${rating} - ${label}`);
      }}
    />
  );
}

📖 API

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | question | string | Required | Question to ask the user | | title | string | "Quick Feedback" | Title of the feedback popup | | delay | number | 10000 | Delay in ms before showing popup | | storageKey | string | "balloonFeedback" | LocalStorage key | | onFeedback | (rating, label) => void | - | Callback when submitted | | balloons | Balloon[] | Default 5 balloons | Custom balloon config | | enableSound | boolean | true | Enable pop sound | | soundUrl | string | - | Custom sound file URL | | position | string | "bottom-right" | Popup position |

Balloon Interface

interface Balloon {
  id: number;
  color: string;      // Hex color
  rating: number;     // Numeric rating (1-5)
  label: string;      // Display label
}

🎨 Customization Examples

Custom Balloons

<BalloonFeedback
  question="How was your experience?"
  balloons={[
    { id: 1, color: '#ff0000', rating: 1, label: '😡 Bad' },
    { id: 2, color: '#ffaa00', rating: 3, label: '😐 OK' },
    { id: 3, color: '#00ff00', rating: 5, label: '😍 Great' },
  ]}
/>

Analytics Integration

<BalloonFeedback
  question="Rate our new feature"
  onFeedback={(rating, label) => {
    // Send to Google Analytics
    gtag('event', 'feedback', {
      rating: rating,
      label: label,
    });

    // Or Microsoft Clarity
    clarity('event', 'feature_feedback', {
      rating,
      label,
    });
  }}
/>

Custom Position

<BalloonFeedback
  question="Enjoying the app?"
  position="center"
  delay={5000}
/>

Disable Sound

<BalloonFeedback
  question="How's our service?"
  enableSound={false}
/>

🎵 Custom Sound

Add your own pop sound:

1. Place pop-sound.mp3 in your public folder
2. Or provide custom URL:

<BalloonFeedback
  question="Rate us!"
  soundUrl="/sounds/custom-pop.mp3"
/>

🌐 Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

📄 License

MIT © Vedhasagaran Mahalingam

🤝 Contributing

Contributions welcome! Please open an issue or PR.

🔗 Links

• GitHub
• npm

Made with 💜 by Vedhasagaran