React SDK

The @swipelux/onramp-react package provides a simple way to embed Swipelux OnRamp into your React application with full TypeScript support.

This package was designed to work with Next.js and other server-side rendering frameworks out of the box.

Integration Steps

Install the Package

Run the following command to install the SDK:

npm install @swipelux/onramp-react

Add the Component to Your App

Swipelux OnRamp is rendered using the <SwipeluxWidget/> component.

App.tsx

import React from "react";
import { SwipeluxWidget } from "@swipelux/onramp-react"; 
 
export default function App() {
  return (
    <SwipeluxWidget
      // Make sure to replace `apiKey` with your own publishable API key
      apiKey="YOUR_PUBLISHABLE_API_KEY"
    />
  );
}

You're All Set!

You've now integrated Swipelux OnRamp into your React app.

Visit your app and confirm that the widget is displayed correctly.

Advanced Configuration

Event Handling

Handle widget events using callback props:

components/CardRailWidget.tsx

import React from 'react';
import { SwipeluxWidget, SwipeluxWidgetProps } from '@swipelux/onramp-react';
 
export default function CardRailWidget() {
  const handleComplete = (orderData: any) => {
    console.log('Purchase completed:', orderData);
    // Handle successful purchase
    // Redirect user, show confirmation, update UI, etc.
  };
 
  const handleError = (error: any) => {
    console.error('Widget error:', error);
    // Handle errors gracefully
    // Show error message, provide support options
  };
 
  const handleUserAction = (action: string, data: any) => {
    console.log('User action:', action, data);
    // Track user behavior for analytics
  };
 
  return (
    <SwipeluxWidget
      apiKey="YOUR_PUBLISHABLE_API_KEY"
      onComplete={handleComplete}
      onError={handleError}
      onUserAction={handleUserAction}
    />
  );
}

Configure Swipelux OnRamp with props:

components/CustomCardRail.tsx

import React from 'react';
import { SwipeluxWidget } from '@swipelux/onramp-react';
 
export default function CustomCardRail() {
  return (
    <SwipeluxWidget
      apiKey="YOUR_PUBLISHABLE_API_KEY"
      // Pre-fill default values
      defaultCryptoCurrency="USDC"
      defaultFiatCurrency="USD"
      defaultNetwork="polygon"
      defaultAmount="100"
      
      // Appearance customization
      theme="dark"
      primaryColor="#10B981"
      
      // Behavior configuration
      allowCurrencyChange={true}
      allowNetworkChange={true}
      hideUnsupportedNetworks={true}
      
      // Order handling
      orderToken={orderToken} // If using server-side order creation
    />
  );
}

TypeScript Support

The React SDK includes full TypeScript definitions:

types/card-rail.ts

import { SwipeluxWidgetProps } from '@swipelux/onramp-react';
 
// Extend the widget props if needed
interface CustomCardRailProps extends SwipeluxWidgetProps {
  userId?: string;
  analyticsId?: string;
}
 
export function CustomCardRail({ userId, analyticsId, ...widgetProps }: CustomCardRailProps) {
  return (
    <div data-user-id={userId} data-analytics-id={analyticsId}>
      <SwipeluxWidget {...widgetProps} />
    </div>
  );
}

Integration Patterns

Embed the widget in a modal for overlay experiences:

components/CardRailModal.tsx

import React, { useState } from 'react';
import { SwipeluxWidget } from '@swipelux/onramp-react';
 
export default function CardRailModal() {
  const [isOpen, setIsOpen] = useState(false);
 
  return (
    <>
      <button onClick={() => setIsOpen(true)}>
        Buy Crypto
      </button>
      
      {isOpen && (
        <div className="modal-overlay">
          <div className="modal-content">
            <button 
              className="close-button"
              onClick={() => setIsOpen(false)}
            >
              ×
            </button>
            
            <SwipeluxWidget
              apiKey="YOUR_PUBLISHABLE_API_KEY"
              onComplete={() => {
                setIsOpen(false);
                // Handle completion
              }}
              onError={() => {
                // Handle errors but keep modal open
              }}
            />
          </div>
        </div>
      )}
    </>
  );
}

Server-side Order Integration

When creating orders programmatically, use the orderToken prop:

components/PrefilledCardRail.tsx

import React, { useEffect, useState } from 'react';
import { SwipeluxWidget } from '@swipelux/onramp-react';
 
interface Props {
  amount: string;
  currency: string;
  network: string;
  userId: string;
}
 
export default function PrefilledCardRail({ amount, currency, network, userId }: Props) {
  const [orderToken, setOrderToken] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);
 
  useEffect(() => {
    // Create order on server
    fetch('/api/create-card-rail-order', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ amount, currency, network, userId })
    })
    .then(res => res.json())
    .then(data => {
      setOrderToken(data.orderToken);
      setLoading(false);
    });
  }, [amount, currency, network, userId]);
 
  if (loading) {
    return <div>Preparing your purchase...</div>;
  }
 
  return (
    <SwipeluxWidget
      apiKey="YOUR_PUBLISHABLE_API_KEY"
      orderToken={orderToken}
    />
  );
}

Next Steps

You've successfully integrated Swipelux OnRamp into your React application. Consider these next steps:

Server-side integration: Create orders programmatically using our REST API
Webhook handling: Set up webhooks for real-time order updates
Widget customization: Learn about advanced customization options

If you're using a server-side integration and create orders using our REST API, use the orderToken prop in the SwipeluxWidget component to initiate the widget with a prepared order.