@twenty1tools/whatif-react

v0.2.0

Published

25 days ago

React wrapper for What If? SDK

0High
0Medium
0Low

rajatkaush1k

react feedback user-insights widget survey analytics user-research contextual-feedback micro-feedback

What If? React SDK

Official React wrapper for the What If? SDK - a beautiful, customizable widget for collecting contextual micro feedback.

Installation

npm install @twenty1tools/whatif-react
# or
pnpm add @twenty1tools/whatif-react
# or
yarn add @twenty1tools/whatif-react

Quick Start

1. Wrap your app with WhatIfProvider

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

function App() {
  return (
    <WhatIfProvider 
      projectId="your-project-id"
      theme={{
        darkMode: 'auto',
        colors: {
          primary: '#f97316',
        },
      }}
    >
      <YourApp />
    </WhatIfProvider>
  );
}

2. Use the useWhatIf hook

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

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

  const handleClick = () => {
    ask('question-id-123', {
      context: { page: 'checkout' },
    });
  };

  return (
    <button onClick={handleClick}>
      Give Feedback
    </button>
  );
}

API Reference

WhatIfProvider

The provider component that initializes the What If? SDK.

Props

projectId (string, required): Your What If? project ID
baseUrl (string, optional): API base URL (default: /api)
theme (ThemeConfig, optional): Theme configuration object
children (ReactNode, required): Your app components

<WhatIfProvider
  projectId="your-project-id"
  baseUrl="/api"
  theme={{
    darkMode: 'auto',
    position: 'bottom-right',
    colors: {
      primary: '#3b82f6',
    },
  }}
>
  {children}
</WhatIfProvider>

useWhatIf

Hook to access What If? functionality.

Returns

ask(questionId: string, options?: AskOptions): Promise<void> - Display a question widget
setTheme(theme: ThemeConfig): void - Update the theme

const { ask, setTheme } = useWhatIf();

// Show a question
await ask('question-123', {
  context: { page: 'pricing' },
  userFingerprint: 'user-abc',
});

// Update theme
setTheme({
  colors: {
    primary: '#10b981',
  },
});

Examples

Next.js App Router

// app/providers.tsx
'use client';

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

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WhatIfProvider
      projectId={process.env.NEXT_PUBLIC_WHATIF_PROJECT_ID!}
      theme={{
        darkMode: 'auto',
      }}
    >
      {children}
    </WhatIfProvider>
  );
}

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

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

// app/page.tsx
'use client';

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

export default function HomePage() {
  const { ask } = useWhatIf();

  return (
    <button onClick={() => ask('welcome-question')}>
      Share Feedback
    </button>
  );
}

Next.js Pages Router

// pages/_app.tsx
import type { AppProps } from 'next/app';
import { WhatIfProvider } from '@twenty1tools/whatif-react';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <WhatIfProvider projectId="your-project-id">
      <Component {...pageProps} />
    </WhatIfProvider>
  );
}

// pages/index.tsx
import { useWhatIf } from '@twenty1tools/whatif-react';

export default function HomePage() {
  const { ask } = useWhatIf();

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

Conditional Question Triggering

'use client';

import { useWhatIf } from '@twenty1tools/whatif-react';
import { useEffect } from 'react';

export default function CheckoutPage() {
  const { ask } = useWhatIf();

  useEffect(() => {
    // Ask after user spends 10 seconds on page
    const timer = setTimeout(() => {
      ask('checkout-question', {
        context: { page: 'checkout', duration: '10s' },
      });
    }, 10000);

    return () => clearTimeout(timer);
  }, [ask]);

  return <div>Checkout Page</div>;
}

Dynamic Theme Switching

'use client';

import { useWhatIf } from '@twenty1tools/whatif-react';
import { useState } from 'react';

export default function Settings() {
  const { setTheme } = useWhatIf();
  const [isDark, setIsDark] = useState(false);

  const toggleTheme = () => {
    setIsDark(!isDark);
    setTheme({
      darkMode: isDark ? 'light' : 'dark',
    });
  };

  return (
    <button onClick={toggleTheme}>
      Toggle Theme
    </button>
  );
}

Theming

The React SDK supports all theming options from the core SDK. See the core SDK documentation for detailed theming options.

Example Themes

Minimal Design

<WhatIfProvider
  projectId="your-project-id"
  theme={{
    shadow: { enabled: false },
    border: {
      radius: '4px',
      buttonRadius: '4px',
    },
    colors: {
      primary: '#000000',
    },
  }}
>
  {children}
</WhatIfProvider>

Playful Design

<WhatIfProvider
  projectId="your-project-id"
  theme={{
    border: {
      radius: '24px',
      buttonRadius: '24px',
    },
    colors: {
      primary: '#ec4899',
      ratingFilled: '#f472b6',
    },
    animation: {
      duration: 600,
      easing: 'cubic-bezier(0.68, -0.55, 0.265, 1.55)',
    },
  }}
>
  {children}
</WhatIfProvider>

TypeScript Support

This package is fully typed with TypeScript. All types are re-exported for convenience:

import type { 
  ThemeConfig, 
  DarkMode, 
  WidgetPosition, 
  ColorPalette,
  AskOptions,
} from '@twenty1tools/whatif-react';

Related Packages

@twenty1tools/whatif - Core SDK for vanilla JavaScript

License

MIT

Support

Documentation