npm package: @feedhog/widget
Description: Embeddable feedback widget for Feedhog
Author: Feedhog
Latest version: 0.4.1

# @feedhog/widget

Embeddable feedback widget for [Feedhog](https://feedhog.com). Add a beautiful feedback collection widget to any website with just a few lines of code.

## Quick Start

### Script Tag (Any Website)

Add this script to your HTML, just before the closing `</body>` tag:

```html
<script
  src="https://feedhog.com/widget.js"
  data-api-key="fhpk_xxx"
  data-position="bottom-right"
  data-primary-color="#3b82f6"
  async
></script>
```

That's it! A floating feedback button will appear on your page.

### Advanced Configuration

For more control, use the `window.feedhogSettings` object:

```html
<script>
  window.feedhogSettings = {
    apiKey: 'fhpk_xxx',
    position: 'bottom-right',
    primaryColor: '#3b82f6',
    triggerText: 'Feedback',
    showTrigger: true,
    title: 'Send us feedback',
    subtitle: 'We\'d love to hear from you',
    // Pre-identify the user
    user: {
      externalId: 'user-123',
      email: 'user@example.com',
      name: 'John Doe'
    }
  };
</script>
<script src="https://feedhog.com/widget.js" async></script>
```

## React / Next.js

Install the package:

```bash
npm install @feedhog/widget
# or
pnpm add @feedhog/widget
```

Use the React component:

```tsx
import { FeedhogWidget } from '@feedhog/widget/react';

function App() {
  const currentUser = useCurrentUser(); // Your auth hook

  return (
    <FeedhogWidget
      apiKey="fhpk_xxx"
      position="bottom-right"
      primaryColor="#3b82f6"
      user={currentUser ? {
        externalId: currentUser.id,
        email: currentUser.email,
        name: currentUser.name
      } : undefined}
    />
  );
}
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | `string` | *required* | Your public API key (starts with `fhpk_`) |
| `baseUrl` | `string` | `https://feedhog.com` | Custom API URL |
| `position` | `string` | `bottom-right` | Button position: `bottom-right`, `bottom-left`, `top-right`, `top-left` |
| `primaryColor` | `string` | `#3b82f6` | Brand color (hex) |
| `triggerText` | `string` | `Feedback` | Button text |
| `showTrigger` | `boolean` | `true` | Show/hide the floating button |
| `title` | `string` | `Send us feedback` | Modal title |
| `subtitle` | `string` | `We'd love to hear from you` | Modal subtitle |
| `user` | `object` | `undefined` | Pre-identified user |

### User Identity

```typescript
interface UserIdentity {
  externalId: string;     // Required: Your user ID
  email?: string;         // Optional
  name?: string;          // Optional
  avatarUrl?: string;     // Optional
  metadata?: Record<string, unknown>; // Optional custom data
}
```

## JavaScript API

After the widget loads, you can control it programmatically:

```javascript
// Open the feedback modal
window.FeedhogWidget.open();

// Close the modal
window.FeedhogWidget.close();

// Identify a user (after login)
window.FeedhogWidget.identify({
  externalId: 'user-123',
  email: 'user@example.com',
  name: 'John Doe'
});

// Clear user identity (after logout)
window.FeedhogWidget.reset();
```

## Custom Trigger

To use your own button instead of the floating button:

```html
<script>
  window.feedhogSettings = {
    apiKey: 'fhpk_xxx',
    showTrigger: false  // Hide default button
  };
</script>
<script src="https://feedhog.com/widget.js" async></script>

<!-- Your custom button -->
<button onclick="window.FeedhogWidget.open()">
  Give Feedback
</button>
```

## Styling

The widget uses Shadow DOM for style isolation, so your page styles won't affect it. The widget automatically adapts to light/dark mode based on `prefers-color-scheme`.

You can customize the primary color using the `primaryColor` option. The widget will automatically calculate text contrast and hover states.

## Bundle Size

- Widget: ~15KB gzipped
- Zero dependencies (uses Preact for rendering)
- Shadow DOM isolation

## License

MIT