# @metricshift/react

The intelligent feedback widget for React applications.
Collect, analyze, and act on user feedback with AI-powered insights — in minutes, not weeks.

MetricShift gives you a drop-in feedback experience that feels native to your product, while quietly powering a structured analytics pipeline behind the scenes.

Fully customize the widget — mode, triggers, form type, colors, avatars — so it feels truly brand-specific, not like a generic feedback tool.

---

## ✨ Features

🚀 **2-Minute Setup** — Drop-in widget with modal, toaster, or inline mode wired automatically

🎨 **Deep Customization** — Colors, variants, avatars, display modes, form schemas

🖼️ **Rich Media Support** — Add personal avatars or branded visuals to the widget

🤖 **AI-Powered Analysis** — Sentiment detection, themes, NPS scoring, summaries

📊 **Analytics-Ready** — Widget events can be streamed into your analytics stack

🔒 **Safe by Design** — Domain restrictions + rate limiting built in

♿ **Accessible** — WCAG-friendly, keyboard & screen-reader support

📱 **Mobile-First** — Works beautifully on all screen sizes

🧩 **TypeScript Ready** — Full types & IntelliSense

---

## 📦 Installation
```bash
npm install @metricshift/react
```

or
```bash
yarn add @metricshift/react
```

---

## 🚀 Quick Start

### 1. Create a MetricShift project

Get your Project ID and API key from
👉 https://metricshift.co

### 2. Wrap your app with the provider
```tsx
import { MetricShiftProvider, FeedbackButton } from '@metricshift/react';

function App() {
  return (
    
      
    
  );
}
```

### 3. Add the feedback button anywhere inside the provider
```tsx

```

### 4. View feedback & AI insights

Open your MetricShift dashboard to explore:

- Real-time feedback stream
- AI sentiment & themes
- NPS & CSAT analytics
- Filters, exports, trends

That's it 🎉

---

## 🧠 Security note

It is safe to use `projectId` and `apiKey` in the frontend.

MetricShift protects your widget with:

- Domain allow-listing (configurable in the dashboard)
- Rate limiting to prevent abuse
- Project-scoped keys (no cross-project access)

---

## 📚 Usage Examples

### ⭐ Default floating button
```tsx

```

### 🎯 NPS survey — fires after 5 seconds
```tsx
import { MetricShiftProvider, FeedbackButton } from '@metricshift/react';
import { NPS_PRESET } from '@metricshift/react';


```

### 😊 CSAT survey
```tsx
import { CSAT_PRESET } from '@metricshift/react';


```

### 🍞 Toaster mode — less intrusive
```tsx

  

```

### 📌 Inline mode — embed directly in a page
```tsx

```

### 🖼️ Avatar / branded button
```tsx
<FeedbackButton
  projectId={projectId}
  apiKey={apiKey}
  appearance={{
    buttonText: 'Talk to us',
    subtitleText: 'We read every response',
    avatarSrc: '/founder-avatar.png',
    avatarAlt: 'Niklas, founder',
    avatarSize: 44,
    variant: 'outline',
    position: 'bottom-right',
  }}
/>
```

### 🔧 Programmatic control

Open and close the widget from anywhere in your app:
```tsx
import { MetricShift } from '@metricshift/react';

// Open the widget
MetricShift.open();

// Close the widget
MetricShift.close();

// Trigger by custom event name
MetricShift.trigger('checkout-complete');
```

### 📡 Event callbacks
```tsx
<FeedbackButton
  projectId={projectId}
  apiKey={apiKey}
  onOpen={() => analytics.track('feedback_opened')}
  onClose={() => analytics.track('feedback_closed')}
  onSuccess={(id) =>
    analytics.track('feedback_submitted', { feedbackId: id })
  }
  onError={(err) =>
    analytics.track('feedback_error', { message: err.message })
  }
/>
```

---

## 🧩 Props

### `FeedbackButton`

| Prop | Type | Default | Description |
|---|---|---|---|
| `projectId` | `string` | **required** | MetricShift project ID |
| `apiKey` | `string` | **required** | Project API key |
| `apiUrl` | `string` | MetricShift cloud | Backend endpoint override |
| `fields` | `FieldConfig[]` | `GENERAL_PRESET` | Form schema — use presets or custom |
| `widgetType` | `'general' \| 'nps' \| 'csat' \| 'custom'` | `'general'` | Tells analytics how to segment data |
| `appearance` | `AppearanceConfig` | see below | Visual and text customisation |
| `onOpen` | `() => void` | — | Fired when widget opens |
| `onClose` | `() => void` | — | Fired when widget closes |
| `onSuccess` | `(id: string) => void` | — | Fired on successful submission |
| `onError` | `(error: Error) => void` | — | Fired on submission error |

### `AppearanceConfig`

| Prop | Type | Default | Description |
|---|---|---|---|
| `buttonText` | `string` | `'Feedback'` | Trigger button label |
| `subtitleText` | `string` | — | Second line on button |
| `variant` | `'solid' \| 'outline' \| 'ghost'` | `'outline'` | Button visual style |
| `primaryColor` | `string` | `'#111827'` | Brand accent color (hex) |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' \| 'inline'` | `'bottom-right'` | Widget placement |
| `avatarSrc` | `string` | — | Avatar / logo image URL |
| `avatarAlt` | `string` | `''` | Accessible alt text for avatar |
| `avatarSize` | `number` | `40` | Avatar diameter in px |
| `welcomeTitle` | `string` | `'Share your feedback'` | Modal heading |
| `welcomeSubtitle` | `string` | — | Modal description line |
| `successMessage` | `string` | `'Thank you!'` | Shown after submission |
| `showBranding` | `boolean` | `true` | Show "Powered by MetricShift" |

### Built-in field presets
```tsx
import {
  GENERAL_PRESET,  // type + rating + text + name + email
  NPS_PRESET,      // 0-10 score + open reason
  CSAT_PRESET,     // emoji scale + optional comment
} from '@metricshift/react';
```

### `WidgetConfig` (via `MetricShiftProvider`)
```tsx
<MetricShiftProvider config={{
  projectId: '...',
  apiKey: '...',
  widget: {
    mode: 'button',          // 'button' | 'toaster' | 'inline'
    trigger: {
      type: 'delay',         // 'manual' | 'auto' | 'delay'
      delay: 3000,           // ms (for delay trigger)
    },
    session: {
      showOnce: true,        // never show again after first display
    },
  }
}}>
```

---

## 📊 Dashboard

Your MetricShift dashboard includes:

- Real-time feedback stream
- AI sentiment & theme clustering
- NPS score, trend, and segment breakdown
- Widget configurator with live preview + embed snippet generator
- QR code feedback experiences for physical touchpoints
- Search, filters & CSV export
- Domain restrictions & rate limits

👉 https://metricshift.co

---

## 💼 Pricing

MetricShift starts free.
For full plan details, limits, and AI token allowances, see:

👉 https://metricshift.co

---

## ❓ FAQ

**Can I customize the feedback form?**

Yes. Use the built-in presets (`NPS_PRESET`, `CSAT_PRESET`, `GENERAL_PRESET`) or pass a fully custom `FieldConfig[]` array with your own questions and field types including text, rating, NPS, CSAT, select, multiselect, and boolean.

**Can I use this with multiple projects or websites?**

Yes. You can manage which domains the widget runs on from the dashboard, and each project has its own isolated API key.

**What display modes are available?**

Three modes: `button` (floating pill → modal), `toaster` (slides up from corner), and `inline` (renders the form directly in the page — ideal for QR landing pages or settings pages).

**What's included in the free tier?**

Feedback collection, dashboard access, AI-powered analysis, and a generous monthly allowance of AI tokens. For up-to-date details see 👉 https://metricshift.co

---

## 📖 Documentation

All documentation and updates live at:
👉 https://metricshift.co

---

## 📝 License

MIT © MetricShift

Built with ❤️ for teams who care about their users.
Start free → https://metricshift.co