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.
This component automatically handles responsive layouts and dynamic height adjustment, making it ideal for a variety of application layouts and screen sizes.

​
Key Features

Responsive Layout

Flexible width options from narrow to full-width to suit any layout needs

Dynamic Height

Automatically adjusts height based on form content

TypeScript Support

Built-in TypeScript definitions for reliable type checking

Error Handling

Built-in error handling with customizable fallback options

​
Installation and Setup

Visit the Github Repo
1

Install Dependencies

Ensure React is installed in your project. The Straddle Embed Component is compatible with React 16.8 and above.
2

Add Component Files

Copy the StraddleEmbedComponent.tsx file into your project’s component directory.
3

Import and Use

Import and implement the component in your application:
import React from 'react';
import StraddleEmbedComponent from './path/to/StraddleEmbedComponent';

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

​
Component Props

​
platformId
string
required
Your unique Straddle platform identifier. This is used to associate the embedded form with your specific account or configuration.
​
env
string
required
A string value representing the Straddle environment in which form submissions are created (e.g., production, sandbox).
​
maxWidth
string
default:"'full'"
Controls the component’s maximum width. Available options:

​
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.
​
URL Parameters
object

​
Using the env Prop

The env prop allows you to indicate whether the embedded Straddle form should create a test account (in your platform’s sandbox environment) or a real, production-level account. This is particularly useful when you’re testing webhook integrations, trialing new features, or verifying payment flows before going live.
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 component implements a sophisticated height management system that combines fixed minimum heights with dynamic content adjustment.
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.
Modifying the minimum height may cause layout instability during the initial load. The default 500px value is recommended for most use cases.

​
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:
1

Primary Script Loading

Attempts to load the Straddle embed script from ‘https://forms.straddle.io/embed.js’
2

Fallback Mechanism

If the script fails to load or execute properly, the component falls back to direct iframe source setting
3

Error Recovery

Implements comprehensive error handling for both script loading and execution failures
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:
​
Width Classes
object
The component’s container uses flex justify-center w-full to ensure proper centering and responsive behavior.

​
Performance Considerations

​
Troubleshooting

If you encounter issues with the embed component, verify these common points:
1

Script Loading

Ensure the Straddle embed script (https://forms.straddle.io/embed.js) is loading correctly in your network tab.
2

Platform ID & env

Verify your platformId and env values are correct and properly formatted. The env prop should match the environment context you intend the form to operate within.
3

Container Size

Check that the parent container provides adequate space for the embed to render properly.
4

Network Connection

Verify there are no network issues preventing the iframe content from loading.

API Documentation

Complete API reference for Embed

Component Examples

More implementation examples and use cases

Troubleshooting Guide

Detailed troubleshooting steps and solutions

Support

Contact Straddle support for additional help