# Gotcha - Complete Documentation

> Gotcha is a developer-first contextual feedback SDK for React. Install via `npm install gotcha-feedback`. It lets developers add feedback buttons to any UI component, collecting star ratings and text feedback tied to specific elements rather than generic page surveys.

Website: https://gotcha.cx
npm: https://www.npmjs.com/package/gotcha-feedback
Dashboard: https://gotcha.cx/dashboard
Email: info@braintwopoint0.com

---

## Table of Contents

1. Installation
2. Quick Start
3. Core Concepts
4. Components Reference
5. Configuration Options
6. Editing Responses
7. API Reference
8. Error Handling
9. Pricing & Plans
10. Use Cases
11. Comparison with Alternatives
12. FAQ

---

## 1. Installation

### npm
```bash
npm install gotcha-feedback
```

### yarn
```bash
yarn add gotcha-feedback
```

### pnpm
```bash
pnpm add gotcha-feedback
```

### Requirements
- React 18+ (peer dependency)
- Node.js 16+

---

## 2. Quick Start

### Basic Setup

```tsx
// App.tsx
import { GotchaProvider, Gotcha } from 'gotcha-feedback';

function App() {
  return (
    <GotchaProvider apiKey="your-api-key">
      <MyApp />
    </GotchaProvider>
  );
}

function MyApp() {
  return (
    <div>
      {/* The parent element must have position: relative */}
      <div style={{ position: 'relative' }}>
        <HeroSection />
        <Gotcha elementId="hero-section" mode="feedback" />
      </div>

      <div style={{ position: 'relative' }}>
        <PricingTable />
        <Gotcha elementId="pricing-table" mode="vote" />
      </div>
    </div>
  );
}
```

### Getting an API Key

1. Sign up at https://gotcha.cx
2. Create a project in the dashboard
3. Copy the API key from project settings
4. Add allowed domains (e.g., localhost:3000, yourdomain.com)

---

## 3. Core Concepts

### Standalone Component (Not a Wrapper)
Gotcha is a standalone component placed as a sibling inside a relative-positioned parent. It positions itself absolutely within that parent. Do NOT use it as a wrapper around your component.

```tsx
{/* CORRECT: Gotcha as a sibling inside a relative-positioned parent */}
<div style={{ position: 'relative' }}>
  <YourComponent />
  <Gotcha elementId="my-feature" mode="feedback" />
</div>

{/* WRONG: Do NOT use Gotcha as a wrapper */}
{/* <Gotcha elementId="my-feature" mode="feedback"><YourComponent /></Gotcha> */}
```

### Element IDs
Each Gotcha instance needs a unique `elementId`. This identifier:
- Links feedback to specific UI elements
- Enables filtering in the dashboard
- Persists across sessions for analytics
- Tracks returning users to allow editing previous responses

### Modes
- **feedback**: Star rating (1-5) with optional text comment
- **vote**: Binary thumbs up/down with optional comment

### Field Visibility (Feedback Mode)
You can control which fields appear in feedback mode:
- `showRating` (default: `true`) - Show/hide the star rating selector
- `showText` (default: `true`) - Show/hide the text input field

This lets you create rating-only, text-only, or combined feedback forms.

### Single Modal Pattern
Only one feedback modal can be open at a time. Opening a new modal automatically closes any existing one.

---

## 4. Components Reference

### GotchaProvider

The context provider that must wrap your app.

```tsx
<GotchaProvider
  apiKey="your-api-key"
  debug={false}
  disabled={false}
>
  {children}
</GotchaProvider>
```

**Props:**

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `apiKey` | string | Yes | - | Your project API key |
| `children` | ReactNode | Yes | - | Your app components |
| `baseUrl` | string | No | - | Override API base URL (for testing/staging) |
| `debug` | boolean | No | false | Enable debug logging |
| `disabled` | boolean | No | false | Disable all Gotcha buttons globally |
| `defaultUser` | GotchaUser | No | {} | Default user metadata applied to all submissions |

### Gotcha

The main component that adds a feedback button to a parent element. Place it inside a relative-positioned container as a sibling to your content.

```tsx
<div style={{ position: 'relative' }}>
  <YourComponent />
  <Gotcha
    elementId="unique-id"
    mode="feedback"
    position="top-right"
  />
</div>
```

**Props:**

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `elementId` | string | Yes | - | Unique identifier for this element |
| `mode` | 'feedback' \| 'vote' | Yes | - | Type of feedback to collect |
| `showText` | boolean | No | true | Show text input in feedback mode |
| `showRating` | boolean | No | true | Show star rating in feedback mode |
| `position` | Position | No | 'top-right' | Button placement |
| `size` | 'sm' \| 'md' \| 'lg' | No | 'md' | Button size |
| `theme` | 'light' \| 'dark' \| 'auto' \| 'custom' | No | 'light' | Color theme |
| `customStyles` | GotchaStyles | No | - | Custom style overrides |
| `visible` | boolean | No | true | Control visibility programmatically |
| `showOnHover` | boolean | No | true | Only show button when parent is hovered |
| `touchBehavior` | TouchBehavior | No | 'always-visible' | Mobile behavior |
| `promptText` | string | No | - | Custom prompt text in modal |
| `placeholder` | string | No | - | Input placeholder text |
| `submitText` | string | No | 'Submit' | Submit button text |
| `thankYouMessage` | string | No | 'Thanks for your feedback!' | Post-submission message |
| `voteLabels` | { up: string; down: string } | No | - | Custom labels for vote buttons |
| `user` | GotchaUser | No | - | User metadata for segmentation |
| `onSubmit` | (response: GotchaResponse) => void | No | - | Called after successful submission |
| `onOpen` | () => void | No | - | Called when modal opens |
| `onClose` | () => void | No | - | Called when modal closes |
| `onError` | (error: GotchaError) => void | No | - | Called on error |

**Position Options:**
- `'top-right'` - Top right corner (default)
- `'top-left'` - Top left corner
- `'bottom-right'` - Bottom right corner
- `'bottom-left'` - Bottom left corner
- `'inline'` - Inline with text (no absolute positioning)

**GotchaStyles Interface:**
```tsx
interface GotchaStyles {
  button?: React.CSSProperties;
  modal?: React.CSSProperties;
  input?: React.CSSProperties;
  submitButton?: React.CSSProperties;
}
```

---

## 5. Configuration Options

### showText and showRating

Control which fields appear in feedback mode:

```tsx
{/* Rating only (no text input) */}
<div style={{ position: 'relative' }}>
  <QuickRating />
  <Gotcha elementId="quick-rate" mode="feedback" showText={false} />
</div>

{/* Text only (no star rating) */}
<div style={{ position: 'relative' }}>
  <CommentBox />
  <Gotcha elementId="comment-box" mode="feedback" showRating={false} />
</div>

{/* Both (default behavior) */}
<div style={{ position: 'relative' }}>
  <FullFeedback />
  <Gotcha elementId="full-feedback" mode="feedback" />
</div>
```

### Domain Allowlisting

API keys only accept requests from allowed domains. Configure in dashboard:
- Development: `localhost:3000`, `localhost:5173`
- Production: `yourdomain.com`, `app.yourdomain.com`

### User Identification

Gotcha automatically generates anonymous user IDs stored in localStorage. For identified users:

```tsx
<Gotcha
  elementId="feature"
  mode="feedback"
  user={{ id: 'user-123', email: 'user@example.com' }}
/>
```

### Vote Labels

Customize the vote button labels:

```tsx
<Gotcha
  elementId="article"
  mode="vote"
  voteLabels={{ up: 'Helpful', down: 'Not helpful' }}
/>
```

### Theme

```tsx
{/* Auto-detect system theme */}
<Gotcha elementId="feature" mode="feedback" theme="auto" />

{/* Force dark mode */}
<Gotcha elementId="feature" mode="feedback" theme="dark" />
```

---

## 6. Editing Responses

Gotcha automatically supports editing previous responses. When a user has already submitted feedback for a given `elementId`:

- The modal pre-fills with their previous rating, text, or vote
- The submit button updates (rather than creates) their response
- The thank-you message shows "Your feedback has been updated!" instead of the default
- This works seamlessly for both feedback and vote modes

No additional configuration is needed. The SDK detects existing responses automatically using the anonymous or identified user ID.

```tsx
{/* User clicks the button again after submitting */}
{/* Their previous response is pre-filled and they can update it */}
<div style={{ position: 'relative' }}>
  <Feature />
  <Gotcha elementId="feature-v2" mode="feedback" />
</div>
```

---

## 7. API Reference

### Submit Response
```
POST https://gotcha.cx/api/v1/responses
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "elementId": "feature-x",
  "mode": "feedback",
  "rating": 5,
  "content": "Great feature!",
  "user": { "id": "anonymous-123" },
  "context": { "url": "https://example.com/page" }
}
```

**Response:**
```json
{
  "id": "resp_abc123",
  "status": "created",
  "createdAt": "2025-01-15T10:30:00Z"
}
```

The `status` field can be `"created"`, `"duplicate"`, or `"updated"` (when editing a previous response).

### List Responses
```
GET https://gotcha.cx/api/v1/responses?elementId=feature-x&mode=feedback&page=1&limit=20
Authorization: Bearer <api-key>
```

**Response:**
```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "hasMore": true
  }
}
```

### GDPR Data Export
```
GET https://gotcha.cx/api/v1/users/:userId/export
Authorization: Bearer <api-key>
```

### GDPR Data Deletion
```
DELETE https://gotcha.cx/api/v1/users/:userId
Authorization: Bearer <api-key>
```

---

## 8. Error Handling

### Error Codes

| Code | Description | Solution |
|------|-------------|----------|
| `INVALID_API_KEY` | API key not found or revoked | Check key in dashboard |
| `ORIGIN_NOT_ALLOWED` | Origin not in allowlist | Add domain in dashboard |
| `RATE_LIMITED` | Too many requests | Wait or upgrade plan |
| `QUOTA_EXCEEDED` | Monthly response limit reached | Upgrade to Pro |
| `INVALID_REQUEST` | Malformed request body | Check payload format |
| `USER_NOT_FOUND` | User ID not found (GDPR endpoints) | Verify user ID |
| `INTERNAL_ERROR` | Server error | Retry or contact support |

### Handling Errors

```tsx
<Gotcha
  elementId="feature"
  mode="feedback"
  onError={(error) => {
    if (error.code === 'RATE_LIMITED') {
      // Show "Please wait" message
    } else if (error.code === 'ORIGIN_NOT_ALLOWED') {
      // Log for debugging
      console.error('Domain not configured:', window.location.origin);
    } else if (error.code === 'QUOTA_EXCEEDED') {
      // Prompt user to upgrade
    }
  }}
/>
```

The SDK also logs a `console.warn` for any submission failure by default, even without an `onError` callback.

---

## 9. Pricing & Plans

### Free Plan
- **Price**: $0/month
- **Responses**: 500/month
- **Projects**: 1
- **Analytics**: Last 30 days
- **Rate limit**: 100 requests/minute
- **Support**: Community

### Pro Plan
- **Price**: $29/month
- **Responses**: Unlimited
- **Projects**: Unlimited
- **Analytics**: Full history
- **Rate limit**: 1000 requests/minute
- **Export**: CSV and JSON
- **Support**: Priority email

### Upgrade
Visit https://gotcha.cx/dashboard/settings to upgrade.

---

## 10. Use Cases

### Feature Feedback
Add to new features to measure user satisfaction:
```tsx
<div style={{ position: 'relative' }}>
  <NewEditor />
  <Gotcha elementId="new-editor-v2" mode="feedback" />
</div>
```

### Rating Only (No Text)
Collect quick star ratings without requiring text:
```tsx
<div style={{ position: 'relative' }}>
  <RecipeCard />
  <Gotcha elementId="recipe-card" mode="feedback" showText={false} />
</div>
```

### Text Comments Only (No Stars)
Collect open-ended comments without a rating:
```tsx
<div style={{ position: 'relative' }}>
  <Article />
  <Gotcha elementId="article-comments" mode="feedback" showRating={false} />
</div>
```

### A/B Testing Sentiment
Compare user reactions to design variations:
```tsx
<div style={{ position: 'relative' }}>
  <CheckoutFlow variant={variant} />
  <Gotcha elementId={`checkout-${variant}`} mode="vote" />
</div>
```

### Documentation Rating
Let users rate help articles:
```tsx
<Gotcha elementId={`docs-${slug}`} mode="vote" position="inline" voteLabels={{ up: 'Helpful', down: 'Not helpful' }} />
```

### Bug Context
Collect bug reports with element context:
```tsx
<div style={{ position: 'relative' }}>
  <DataTable />
  <Gotcha elementId="data-table" mode="feedback" promptText="Report an issue" />
</div>
```

### Onboarding Flow
Measure satisfaction at each step:
```tsx
{steps.map((step, i) => (
  <div key={i} style={{ position: 'relative' }}>
    <OnboardingStep {...step} />
    <Gotcha elementId={`onboarding-step-${i}`} mode="feedback" />
  </div>
))}
```

---

## 11. Comparison with Alternatives

### Gotcha vs Hotjar
| Feature | Gotcha | Hotjar |
|---------|--------|--------|
| Element-level feedback | Yes | No (page-level) |
| React SDK | Native | Embed script |
| Bundle size | 15KB | 50KB+ |
| Pricing | $29/mo unlimited | $99/mo+ |
| Self-hosted option | Coming soon | No |

### Gotcha vs Typeform
| Feature | Gotcha | Typeform |
|---------|--------|----------|
| In-context feedback | Yes | No (separate page) |
| Developer experience | React components | Embed iframe |
| Response attribution | By UI element | By form |
| Real-time | Yes | Webhook delay |

### Gotcha vs Custom Solution
| Feature | Gotcha | Build Your Own |
|---------|--------|----------------|
| Setup time | 5 minutes | Days/weeks |
| Dashboard | Included | Build yourself |
| Maintenance | Managed | Your responsibility |
| Cost | $29/mo | Engineering time |

---

## 12. FAQ

**Q: Does Gotcha work with Next.js?**
A: Yes, Gotcha works with Next.js App Router and Pages Router. Use the client-side provider.

**Q: Can I customize the button appearance?**
A: The button uses a glassmorphism "G" design. You can pass `customStyles` to override button, modal, input, and submit button styles.

**Q: Is feedback anonymous?**
A: By default, yes. Gotcha generates anonymous IDs. You can optionally pass identified user data via the `user` prop.

**Q: How is data stored?**
A: Data is stored in secure cloud infrastructure. GDPR compliant with data export/deletion APIs.

**Q: Can I export my data?**
A: Pro plan includes CSV and JSON export. Free plan can use the API for programmatic access.

**Q: What happens if I exceed the free limit?**
A: New responses are rejected with a `QUOTA_EXCEEDED` error until the next billing cycle or you upgrade.

**Q: Is there a self-hosted option?**
A: Coming soon. Contact info@braintwopoint0.com for inquiries.

**Q: Can users edit their feedback?**
A: Yes. When a user clicks the Gotcha button on an element they have already submitted feedback for, the modal pre-fills their previous response and lets them update it.

**Q: How does Gotcha handle the button on mobile?**
A: By default, the button is always visible on touch devices (`touchBehavior: 'always-visible'`). You can set `touchBehavior: 'tap-to-reveal'` for tap-based interaction. On mobile, the modal renders as a full-screen portal overlay.

---

## Support

- Documentation: https://gotcha.cx
- Email: info@braintwopoint0.com
- npm: https://www.npmjs.com/package/gotcha-feedback

---

Last updated: February 2026