Embed React Component

The Embed component provides a seamless way to integrate Straddle forms into your React application. This guide covers everything you need to know about implementing and customizing the component.

​

Key Features

​

Installation and Setup

import React from 'react';
import StraddleEmbedComponent from './path/to/StraddleEmbedComponent';

function MyComponent() {
  return (
    <StraddleEmbedComponent 
      platformId="your-platform-id" 
      env="your-env-value" 
    />
  );
}

​

Component Props

​

Implementation Examples

​

Basic Usage

import React from 'react';
import StraddleEmbedComponent from './StraddleEmbedComponent';

function MyComponent() {
  return (
    <StraddleEmbedComponent 
      platformId="your-platform-id"
      env="sandbox" // Always use sandbox for testing
    />
  );
}

​

Responsive Implementation

import React, { useState, useEffect } from 'react';
import StraddleEmbedComponent from './StraddleEmbedComponent';

function ResponsiveStraddleEmbed() {
  const [maxWidth, setMaxWidth] = useState('full');

  useEffect(() => {
    const mediaQuery = window.matchMedia('(min-width: 768px)');
    
    const handleMediaQueryChange = (e) => {
      setMaxWidth(e.matches ? 'medium' : 'full');
    };

    mediaQuery.addListener(handleMediaQueryChange);
    handleMediaQueryChange(mediaQuery);

    return () => mediaQuery.removeListener(handleMediaQueryChange);
  }, []);

  return (
    <StraddleEmbedComponent 
      platformId="your-platform-id"
      env="sandbox"
      maxWidth={maxWidth}
    />
  );
}

​

Configuration Details

​

URL Parameters

The Straddle embed URL includes several preconfigured parameters that control the form’s appearance and behavior. These parameters are automatically set in the component for optimal integration. The env value is not injected into the URL, but is instead provided as a separate data attribute, making it accessible to the embedded form internally.

​

Using the env Prop

How It Works:

• Sandbox Environment:
  When env is set to a value indicating a sandbox or test environment (e.g., env="sandbox"), the embedded form will create new accounts in your sandbox environment. This ensures you can safely experiment, test your integrations, and verify webhook responses without impacting live data or existing real accounts.
• Production Environment:
  When env is set to production, the embedded form operates against your real, production-level environment. Accounts created, data submitted, and webhooks triggered from this embedded form will reflect actual usage scenarios and should be treated as live, customer-facing transactions.

No Direct URL Changes:
The env value is not appended to the Straddle form URL. Instead, it’s passed as a data attribute on the iframe (i.e., env), allowing the form itself (within the iframe) to interpret and act upon the environment setting. This ensures that the same URL can be used consistently, while the underlying logic—such as which database endpoints or webhook routes to invoke—is dynamically adjusted based on env.

Recommended Usage:

• Use env="sandbox" whenever you’re testing new integrations, verifying that your webhook listeners work correctly, or experimenting with new features.
• Switch to env="production" only when you’re ready for real-world usage, ensuring that account creations, messages, and webhooks are fully integrated into your live environment.

​

Dynamic Height Behavior

The dynamic height functionality works through two mechanisms:

1. The dynamicHeight=1 URL parameter enables the embed to communicate its content height.
2. A minimum height of 500px is enforced via inline styles to prevent layout shifts during loading.

​

TypeScript Integration

The component includes comprehensive TypeScript definitions for enhanced development experience:

interface StraddleEmbedComponentProps {
  platformId: string;
  env: string; // Now included as a required prop
  maxWidth?: 'narrow' | 'medium' | 'wide' | 'full' | 'auto';
}

​

Script Loading and Error Handling

The component implements robust script loading with automatic fallbacks:

const handleScriptError = () => {
  console.error('Failed to load the Straddle embed script.')
  loadEmbeds()
}

if (!existingScript) {
  const script = document.createElement('script')
  script.src = embedScriptSrc
  script.async = true
  script.onload = loadEmbeds
  script.onerror = handleScriptError
  document.body.appendChild(script)
}

​

Advanced Usage

​

Error Handling

import React from 'react';
import ErrorBoundary from './ErrorBoundary';
import StraddleEmbedComponent from './StraddleEmbedComponent';

function MyComponent() {
  return (
    <ErrorBoundary fallback={<div>Error loading Straddle form</div>}>
      <StraddleEmbedComponent 
        platformId="your-platform-id"
        env="production"
      />
    </ErrorBoundary>
  );
}

​

Best Practices

​

Custom Component Integration

The Straddle Embed Component can be wrapped with custom components to extend its functionality:

import React from 'react';
import StraddleEmbedComponent from './StraddleEmbedComponent';

const CustomStraddleContainer: React.FC = () => {
  return (
    <div className="my-custom-container">
      <h2>Account Setup</h2>
      <StraddleEmbedComponent 
        platformId="your-platform-id"
        env="production"
        maxWidth="medium"
      />
      <div className="support-text">
        Need help? Contact support
      </div>
    </div>
  );
};

​

Styling Integration

The component uses Tailwind CSS classes for layout management. Here’s how different width options map to Tailwind classes:

​

Performance Considerations

​

Troubleshooting

​

Related Resources