Vortex React Component

High-performance React component for Vortex invitations with intelligent provider integration.

🚀 Quick Start

npm install @teamvortexsoftware/vortex-react

Basic Usage (Standalone)

import { VortexInvite } from '@teamvortexsoftware/vortex-react';

function MyComponent() {
  return (
    <VortexInvite
      componentId="my-widget"
      jwt="eyJhbGciOiJIUzI1NiIs..."
      isLoading={false}
      scope="team-123"
      scopeType="team"
      onInvite={handleInvite}
    />
  );
}

⚡ Dead Simple Usage (with VortexProvider)

For the ultimate simplified experience, create a wrapper component in your app:

npm install @teamvortexsoftware/vortex-react @teamvortexsoftware/vortex-react-provider

// Create this wrapper component in your app:
import { VortexInvite } from '@teamvortexsoftware/vortex-react';
import { useVortexJWT, useVortexAuth } from '@teamvortexsoftware/vortex-react-provider';

const VortexInviteSimple = (props) => {
  const { jwt, isLoading } = useVortexJWT();
  const { user } = useVortexAuth();

  return (
    <VortexInvite
      jwt={jwt || ''}
      isLoading={isLoading || false}
      {...props}
    />
  );
};

// Now use it anywhere in your app - dead simple!
function MyInviteComponent() {
  return (
    <VortexInviteSimple
      componentId="my-widget"
      scope="team-123"
      scopeType="team"
      onInvite={handleInvite}
    />
  );
}

function App() {
  return (
    <VortexProvider config={{ apiBaseUrl: '/api/vortex' }}>
      <MyInviteComponent />
    </VortexProvider>
  );
}

🎯 Provider Integration Benefits

Using VortexInvite with VortexProvider gives you powerful state management:

Consistent State Management:

• Centralized JWT: All components share the same authentication state
• Automatic Refresh: JWT tokens refresh automatically across all components
• Error Handling: Unified error management through provider context

Massively Reduced Boilerplate:

Choose your level of simplicity:

// Traditional: Manual prop management
<VortexInvite
  componentId="my-widget"
  jwt={jwt}
  isLoading={isLoading}
  scope="team-123"
  scopeType="team"
  onInvite={handleInvite}
/>

// Dead Simple: Local wrapper pattern (recommended)
<VortexInviteSimple
  componentId="my-widget"
  scope="team-123"
  scopeType="team"
  onInvite={handleInvite}
/>

📋 Complete Props Reference

VortexInvite (Traditional)

| Prop | Type | Required | Description | Docs | | ----------- | --------- | -------- | ---------------------------- | ----------------------------------------------------------------------------- | | componentId | string | ✅ | Component identifier | docs | | jwt | string | ✅ | JWT token for authentication | docs | | scope | string | ✅ | Scope identifier (e.g., team ID) | docs | | scopeType | string | ✅ | Scope type (e.g., "team") | docs | | isLoading | boolean | ❌ | Loading state indicator | docs |

VortexInviteSimple (Local Wrapper Pattern)

| Prop | Type | Required | Description | Docs | | ------------------------- | ------------------------ | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------- | | componentId | string | ✅ | Component identifier | docs | | scope | string | ✅ | Scope identifier (e.g., team ID) | docs | | scopeType | string | ✅ | Scope type (e.g., "team") | docs | | jwt | string | ❌ | Auto-provided by your wrapper component | docs | | isLoading | boolean | ❌ | Auto-provided by your wrapper component | docs | | onEvent | function | ❌ | Event handler for component events | docs | | onSubmit | function | ❌ | Form submission handler | | | onInvite | function | ❌ | Invitation completion handler | docs | | onError | function | ❌ | Error handler | | | emailValidationFunction | function | ❌ | Custom email validation | docs | | analyticsSegmentation | Record<string, any> | ❌ | Analytics tracking data | | | userEmailsInGroup | string[] | ❌ | Pre-populated email list | docs | | templateVariables | Record<string, string> | ❌ | Template variables | docs | | googleAppClientId | string | ❌ | Google integration client ID | docs | | googleAppApiKey | string | ❌ | Google integration API key | docs |

🔄 Backward Compatibility

100% backward compatible - existing implementations work unchanged:

// ✅ This still works exactly as before
<VortexInvite
  componentId="my-widget"
  jwt={jwt}
  isLoading={loading}
  scope="team-123"
  scopeType="team"
  // ... all other props
/>

📖 Advanced Examples

With Custom Event Handlers

<VortexInvite
  componentId="advanced-widget"
  onInvite={(data) => {
    console.log('Invitation sent:', data);
    trackAnalyticsEvent('invitation_sent', data);
  }}
  onError={(error) => {
    console.error('Invitation error:', error);
    showErrorToast(error.message);
  }}
/>

With Custom Validation

<VortexInvite
  componentId="validated-widget"
  emailValidationFunction={async (email) => {
    const isValid = await validateEmailInSystem(email);
    return {
      valid: isValid,
      message: isValid ? 'Valid' : 'Email not found in system',
    };
  }}
/>

Mixed Provider and Explicit Props

<VortexProvider config={{ apiBaseUrl: '/api/vortex' }}>
  <VortexInvite
    componentId="hybrid-widget"
    // jwt, isLoading automatically from provider
    scope="workspace-456"
    scopeType="workspace"
    analyticsSegmentation={customAnalytics} // Custom tracking
    onInvite={handleInvite}
  />
</VortexProvider>

🛠️ TypeScript Support

Full TypeScript support with exported interfaces:

import type { VortexInviteProps } from '@teamvortexsoftware/vortex-react';

const MyComponent: React.FC<{ config: VortexInviteProps }> = ({ config }) => {
  return <VortexInvite {...config} />;
};

🚨 Error Handling

The component gracefully handles all scenarios:

• ✅ No Provider: Uses explicit props only
• ✅ Provider Error: Falls back to explicit props
• ✅ Missing Props: Safe defaults applied
• ✅ Mixed Usage: Explicit props override provider

🔧 Best Practices

1. Dead Simple with Provider

<VortexProvider config={{ apiBaseUrl: '/api/vortex' }}>
  {/* All components automatically get jwt and isLoading */}
  <VortexInviteWithProvider
    componentId="widget-1"
    scope="team-1"
    scopeType="team"
    onInvite={handleInvite1}
  />
  <VortexInviteWithProvider
    componentId="widget-2"
    scope="team-2"
    scopeType="team"
    onInvite={handleInvite2}
  />
  <VortexInviteWithProvider
    componentId="widget-3"
    scope="workspace-1"
    scopeType="workspace"
    onInvite={handleInvite3}
  />
</VortexProvider>

2. Override Provider Data When Needed

<VortexInviteWithProvider
  componentId="special-widget"
  scope="special-team"
  scopeType="team"
  jwt={customJWT} // Override provider JWT for this instance
  // isLoading still comes from provider automatically
/>

3. Standalone for Simple Cases

// No provider needed for simple, one-off usage
<VortexInvite
  componentId="simple-widget"
  jwt={staticJWT}
  isLoading={false}
  scope="team-123"
  scopeType="team"
  onInvite={handleInvite}
/>

📦 What's New

• 🎯 Two Component Options - Choose VortexInvite (traditional) or VortexInviteWithProvider (dead simple)
• 🔄 100% Backward Compatible - Existing VortexInvite usage works unchanged
• ⚡ Dead Simple Experience - VortexInviteWithProvider eliminates jwt and isLoading props
• 🛡️ Explicit Override - Your props always override provider values
• 🚀 Zero Configuration - Just wrap with VortexProvider and use VortexInviteWithProvider
• 🔒 Safe Imports - No crashes when provider package isn't installed

🔗 Related Packages

• @teamvortexsoftware/vortex-react-provider - Context provider for state management
• @teamvortexsoftware/vortex-nextjs-15-sdk - Next.js API route handlers

Need help? Check out the demo implementation for complete examples.