React SDK (`@orderly/embed-react`)

A drop-in React component for rendering the Orderly embed. Uses the fetchClientSecret pattern for secure authentication.

Installation


npm install @orderly/embed-react

Requires React 18 or later.

Quick Start


import { OrderlyEmbed } from '@orderly/embed-react'
 
function IntegrationsPage() {
  return (
    <OrderlyEmbed
      fetchClientSecret={() =>
        fetch('/api/orderly/session', { method: 'POST' })
          .then(r => r.json())
          .then(d => d.clientSecret)
      }
      appearance={{ primaryColor: '#6366f1' }}
      onBridgeCreated={(bridge) => console.log('Created:', bridge)}
    />
  )
}

This requires a server-side endpoint that creates sessions using @orderly/node.

Props

Prop	Type	Required	Description
`fetchClientSecret`	`() => Promise<string>`	Yes	Async function that returns an `est_` token from your server
`mode`	`'full' \| 'connect'`	No	Display mode
`slug`	`string`	No	Branding slug
`appearance`	`EmbedAppearance`	No	Visual overrides
`allowedBridgeTypes`	`string[]`	No	Restrict available bridge types
`embedOrigin`	`string`	No	Override embed origin URL
`onReady`	`() => void`	No	Called when the embed is loaded and interactive
`onBridgeCreated`	`(bridge) => void`	No	Called when a bridge is created
`onBridgeUpdated`	`(bridge) => void`	No	Called when a bridge is updated
`onBridgeDeleted`	`(bridge) => void`	No	Called when a bridge is deleted
`onError`	`(error) => void`	No	Called when an error occurs
`className`	`string`	No	CSS class for the container div
`style`	`CSSProperties`	No	Inline styles for the container

`EmbedAppearance`


{
  primaryColor?: string   // e.g. '#6366f1'
  borderRadius?: string   // e.g. '8px'
  fontFamily?: string     // e.g. 'Inter, sans-serif'
}

`BridgeEvent`

Passed to onBridgeCreated, onBridgeUpdated, and onBridgeDeleted:


{
  id: string    // Bridge UUID
  type: string  // e.g. 'shopify', 'shipstation'
  name: string  // Display name
}

Session Refresh

Session refresh is automatic. When the session is about to expire, the component calls fetchClientSecret again to get a fresh token and sends it to the iframe via postMessage. No manual handling required.

Appearance Updates

Appearance changes are pushed to the iframe in real time:


const [color, setColor] = useState('#6366f1')
 
<OrderlyEmbed
  fetchClientSecret={fetchSecret}
  appearance={{ primaryColor: color }}
/>
 
// Updating `color` will push the change to the embed immediately

OAuth

OAuth flows (e.g. Shopify) are handled automatically. The embed requests a popup window, the SDK opens it, and the embed detects when the OAuth flow completes.

Full Example


'use client'
 
import { useCallback } from 'react'
import { OrderlyEmbed } from '@orderly/embed-react'
import type { BridgeEvent } from '@orderly/embed-react'
 
export default function IntegrationsPage() {
  const fetchClientSecret = useCallback(async () => {
    const res = await fetch('/api/orderly/session', { method: 'POST' })
    if (!res.ok) throw new Error('Failed to create session')
    const data = await res.json()
    return data.clientSecret
  }, [])
 
  return (
    <div className="max-w-4xl mx-auto p-6">
      <h1>Integrations</h1>
      <OrderlyEmbed
        fetchClientSecret={fetchClientSecret}
        slug="my-company"
        appearance={{
          primaryColor: '#6366f1',
          borderRadius: '12px',
        }}
        onReady={() => console.log('Embed ready')}
        onBridgeCreated={(bridge: BridgeEvent) => {
          console.log('Bridge created:', bridge)
          // Refresh your local state, show a toast, etc.
        }}
        onError={(error) => console.error('Embed error:', error)}
        className="mt-4"
      />
    </div>
  )
}

React SDK (@orderly/embed-react)