Developer-first contextual feedback SDK
npm install gotcha-feedbackA developer-first contextual feedback SDK for React. Add a feedback button to any component with a single line of code.
``bash`
npm install gotcha-feedbackor
yarn add gotcha-feedbackor
pnpm add gotcha-feedback
`tsx
import { GotchaProvider, Gotcha } from 'gotcha-feedback';
function App() {
return (
);
}
function FeatureCard() {
return (
Check out this awesome new feature!
Features
- Feedback Mode - Star rating + text input
- Vote Mode - Thumbs up/down
- User Segmentation - Analyze feedback by custom user attributes
- Edit Support - Users can update their previous submissions
- Customizable - Themes, sizes, positions
- Accessible - Full keyboard navigation and screen reader support
- Animated - Smooth enter/exit animations with CSS transitions
- Lightweight - ~15KB minified
Props
$3
| Prop | Type | Default | Description |
|------|------|---------|-------------|
|
| string | Required | Your Gotcha API key |
| baseUrl | string | https://gotcha.cx/api/v1 | Override API endpoint |
| debug | boolean | false | Enable debug logging |
| disabled | boolean | false | Disable all Gotcha buttons |
| defaultUser | object | {} | Default user metadata |$3
| Prop | Type | Default | Description |
|------|------|---------|-------------|
|
elementId | string | Required | Unique identifier for this element |
| mode | 'feedback' \| 'vote' | 'feedback' | Feedback mode |
| position | 'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left' \| 'inline' | 'top-right' | Button position |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Button size |
| theme | 'light' \| 'dark' \| 'auto' | 'light' | Color theme |
| showOnHover | boolean | true | Only show on hover |
| promptText | string | Mode-specific | Custom prompt text |
| user | object | - | User metadata for segmentation |
| onSubmit | function | - | Callback after submission |
| onOpen | function | - | Callback when modal opens |
| onClose | function | - | Callback when modal closes |Examples
$3
`tsx
Feature Title
`$3
tsx
mode="vote"
promptText="Is this pricing fair?"
/>
`$3
tsx
theme="dark"
/>
`$3
Pass user metadata for segmentation and analytics. When a
is provided, users can also edit their previous submissions.`tsx
// Set default user data at the provider level
defaultUser={{ plan: 'pro', role: 'admin' }}
>
`tsx
// Pass dynamic user data from your app
user={{
id: currentUser.id, // Required for edit functionality
email: currentUser.email,
plan: currentUser.subscription,
age: currentUser.age,
country: currentUser.country,
company: currentUser.company
}}
/>
`tsx
// Or capture device/browser info
user={{
id: user.id,
deviceType: isMobile ? 'mobile' : 'desktop',
browser: navigator.userAgent.includes('Chrome') ? 'Chrome' : 'Other',
locale: navigator.language
}}
/>
`Pass any attributes relevant to your use case. Supported value types:
, number, boolean, or null.$3
`tsx
onSubmit={(response) => {
console.log('Feedback submitted:', response);
analytics.track('feedback_submitted', { elementId: 'feature' });
}}
onError={(error) => {
console.error('Feedback error:', error);
}}
/>
`Hooks
$3
Access the Gotcha context for programmatic control:
tsx
import { useGotcha } from 'gotcha-feedback';function MyComponent() {
const { submitFeedback, disabled } = useGotcha();
const handleCustomSubmit = async () => {
await submitFeedback({
elementId: 'custom',
mode: 'feedback',
rating: 5,
content: 'Great feature!',
});
};
return ;
}
`User Metadata & Segmentation
When you pass custom attributes in the
prop, Gotcha automatically tracks them and enables segmentation in your dashboard.$3
1. Pass user attributes when rendering the Gotcha component
2. View segmented analytics in your dashboard under Analytics > Segments
3. Filter and compare feedback by user attributes (plan, age, location, etc.)
$3
`tsx
// Segment by subscription plan
// → Compare how free vs. pro users feel about pricing// Segment by device type
// → See if mobile users have different pain points
// Segment by country
// → Understand regional differences in feedback
// Segment by user tenure
30 ? 'established' : 'new' }} />
// → Compare new user vs. power user sentiment
`In your dashboard under Analytics > Segments, you can group responses by any of these attributes.
Edit Previous Submissions
When you provide a
, users can update their previous feedback instead of creating duplicates.$3
1. User submits feedback for an element
2. User returns later and opens the same feedback modal
3. Their previous response is automatically loaded
4. They can modify and re-submit to update their feedback
`tsx
user={{ id: 'user_123' }} // Required for edit functionality
/>
`The modal will show "Update" instead of "Submit" when editing, and previous values will be pre-filled.
TypeScript
The package includes full TypeScript definitions:
tsx
import type { GotchaProps, GotchaProviderProps } from 'gotcha-feedback';
``- React 18+
MIT