Documentation
WhatifQuick Start

Quick Start

Build your first feedback widget in 5 minutes 🚀

Quick Start Guide

Let's build a beautiful feedback widget from scratch. This guide works for both React and vanilla JavaScript.

Step 1: Get Your Project ID

First, create a project in your dashboard to get your unique Project ID.

Dashboard → New Project → Copy Project ID

Step 2: Choose Your Path

Install the Package

npm install @twenty1tools/whatif

Setup Provider

Wrap your app with the WhatIfProvider:

App.tsx
import { WhatIfProvider } from '@twenty1tools/whatif';

function App() {
  return (
    <WhatIfProvider
      projectId="your-project-id"
      user={{
        id: 'user_123',        // Required for smart filtering
        name: 'John Doe',      // Optional display data
      }}
      org={{
        name: 'Acme Corp'      // Optional organization tracking
      }}
    >
      <YourApp />
    </WhatIfProvider>
  );
}

Add a Trigger

Use the hook anywhere in your app:

components/FeedbackButton.tsx
import { useWhatIf } from '@twenty1tools/whatif';

export function FeedbackButton() {
  const { ask } = useWhatIf();

  // Simple call - user/org data already configured in provider
  return (
    <button
      onClick={() => ask('your-question-id')}
      className="btn btn-primary"
    >
      Give Feedback
    </button>
  );
}

That's it! 🎉 The widget will automatically appear when users click the button.

Install the Package

npm install @twenty1tools/whatif

Create Provider Component

app/providers.tsx
'use client';

import { WhatIfProvider } from '@twenty1tools/whatif';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WhatIfProvider projectId="your-project-id">
      {children}
    </WhatIfProvider>
  );
}

Add to Root Layout

app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Add a Trigger

app/components/FeedbackButton.tsx
'use client';

import { useWhatIf } from '@twenty1tools/whatif';

export function FeedbackButton() {
  const { ask } = useWhatIf();
  return <button onClick={() => ask('question-id')}>Feedback</button>;
}

Perfect! 🚀 Your Next.js app now has feedback widgets.

With global initialization, you can now use the ultra-simple API:

Anywhere in your app
import { useWhatIf } from '@twenty1tools/whatif';

function FeedbackButton() {
  const { ask } = useWhatIf();

  return (
    <button onClick={() => ask('your-question-id')}>
      Give Feedback
    </button>
  );
}

No need to pass user/org data every time - it's already configured!

Install the Package

npm install @twenty1tools/whatif

Or use CDN:

<script type="module">
  import { WhatIf } from 'https://unpkg.com/@twenty1tools/whatif';
</script>

Initialize SDK

main.js
import { WhatIf } from '@twenty1tools/whatif';

const whatif = new WhatIf('your-app-id');

Add a Trigger

document.getElementById('feedback-btn').addEventListener('click', () => {
  whatif.ask('your-question-id');
});
index.html
<button id="feedback-btn">Give Feedback</button>

Done! ✨ Click the button to see your widget.

Step 3: Create Your First Question

Head to your dashboard and create a question:

  1. Go to your project → Questions tab

  2. Click "New Question"

  3. Choose a type:

    • 📊 Rating - Star ratings (1-5)
    • ✅ Single Choice - Multiple choice questions
    • 💬 Text - Open-ended feedback

  4. Write your question:

    Example: "How would you rate your experience?"

  5. Copy the Question ID from the dashboard

  6. Use it in your code:

    whatif.ask('question-id-from-dashboard');

Step 4: Customize (Optional)

Make the widget match your brand:

const whatif = new WhatIf('your-app-id', '/api', {
  darkMode: 'auto',
  colors: {
    primary: '#3b82f6',  // Your brand color
  },
  position: 'bottom-right',
});

Want more customization? Check out the Theming Guide for 50+ customization options.

What's Happening?

When a user clicks your trigger:

  1. 🎯 Question loads from your dashboard
  2. 🎨 Widget appears with smooth animation
  3. ✍️ User responds through the widget
  4. ✅ Response saves automatically
  5. 📊 Data appears in your dashboard

Step 5: Add User Context (Important!)

⚠️ Important: Always include user context with a unique id to prevent questions from showing repeatedly to the same user.

Set user data once in your provider - it will be automatically used for all questions:

App.tsx
<WhatIfProvider
  projectId="your-project-id"
  user={{
    id: 'user_unique_id',        // ⚠️ REQUIRED - prevents repeated questions
    name: 'Sarah Chen',           // Optional - for dashboard display
    email: 'sarah@example.com',   // Optional - for dashboard display
    avatar: 'https://example.com/avatar.jpg' // Optional - for dashboard display
  }}
  org={{
    name: 'Acme Corp',            // Optional - for organization display
    logo: 'https://example.com/logo.png'     // Optional - for dashboard display
  }}
>
  <YourApp />
</WhatIfProvider>

Usage - Automatic Data Pickup

const { ask } = useWhatIf();

// ✅ Uses provider data automatically
ask('checkout-question');

// ✅ Override for specific cases
ask('admin-feedback', {
  user: { id: 'admin_user', name: 'Admin' },
  context: { page: 'admin-panel' }
});

Manual Setup (Without Provider)

If not using the provider, pass user data with each question:

whatif.ask('question-id', {
  user: {
    id: 'user_unique_id',        // ⚠️ REQUIRED - prevents repeated questions
    name: 'Sarah Chen',           // Optional - enhances dashboard display
    email: 'sarah@example.com',   // Optional - enhances dashboard display
    avatar: 'https://example.com/avatar.jpg' // Optional - enhances dashboard display
  },
  context: {
    page: 'checkout',
    feature: 'new-payment'
  }
});

Why user.id matters: Without a unique identifier, WhatIf can't track which users have seen questions, causing the same question to appear repeatedly.

Automatic Data: WhatIf automatically captures timestamp, browser, device, page info, and previous URL with every response - no code needed! See the Context Guide for details.

Testing

Test your widget locally:

// Trigger the widget programmatically
whatif.ask('question-id');

// Or test with user/org/context data
whatif.ask('question-id', {
    user: {
    id: 'test_user_123',
      name: 'Test User',
    email: 'test@example.com',
    avatar: 'https://example.com/avatar.jpg'
  },
  org: {
    name: 'Test Corp',
    logo: 'https://example.com/logo.png'
    },
  context: {
    page: 'checkout',
    environment: 'development'
  }
});

Common Use Cases

🛒 After Checkout

// When order completes
whatif.ask('checkout-satisfaction');

⭐ Feature Launch

// When user tries new feature
whatif.ask('new-feature-feedback');

🎯 Exit Intent

// Before user leaves
document.addEventListener('mouseleave', () => {
  whatif.ask('exit-survey');
});

⏱️ After Time

// After 30 seconds on page
setTimeout(() => {
  whatif.ask('page-experience');
}, 30000);

Next Steps

📊 Context & Data

Automatic data + user/org display

🎨 Theming

Match your brand perfectly

🌓 Dark Mode

Auto-detect user preference

🚀 Product Use Cases

Industry-specific implementation examples

Need Help?

On this page

Quick Start GuideStep 1: Get Your Project IDStep 2: Choose Your PathInstall the PackageSetup ProviderAdd a TriggerInstall the PackageCreate Provider ComponentAdd to Root LayoutAdd a TriggerSimplified Usage (Recommended)Install the PackageInitialize SDKAdd a TriggerStep 3: Create Your First QuestionStep 4: Customize (Optional)What's Happening?Step 5: Add User Context (Important!)Provider-Level Setup (Recommended)Usage - Automatic Data PickupManual Setup (Without Provider)TestingCommon Use CasesNext StepsNeed Help?